excel-model 0.1.0__tar.gz

excel_model-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+*.egg
+
+# pixi
+.pixi/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Testing
+.pytest_cache/
+.hypothesis/
+.coverage
+htmlcov/
+
+# Docs
+site/

excel_model-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthias Christenson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

excel_model-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.4
+Name: excel-model
+Version: 0.1.0
+Summary: YAML-driven Excel financial model generator
+Project-URL: Documentation, https://neuralsignal.github.io/excel-model/
+Project-URL: Repository, https://github.com/neuralsignal/excel-model
+Author: Matthias Christenson
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dcf,excel,financial-model,openpyxl,p&l,scenario,yaml
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.12
+Requires-Dist: click<9,>=8.0
+Requires-Dist: dacite<2,>=1.8
+Requires-Dist: openpyxl<4,>=3.1
+Requires-Dist: polars<2,>=1.0
+Requires-Dist: pyyaml<7,>=6.0
+Requires-Dist: strictyaml<2,>=1.3
+Provides-Extra: dev
+Requires-Dist: hypothesis<7,>=6.0; extra == 'dev'
+Requires-Dist: pytest-cov<6,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# excel-model
+
+YAML-driven Excel financial model generator.
+
+Build professional financial models (P&L, DCF, Budget vs Actuals, Scenario Analysis) from declarative YAML specs. Generates `.xlsx` workbooks with named ranges, styled sheets, and Excel formulas using openpyxl.
+
+## Installation
+
+```bash
+pip install excel-model
+```
+
+Or for development:
+
+```bash
+pixi install
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Build a P&L model
+excel-model build --spec model.yaml --output model.xlsx --mode batch
+
+# Validate a spec
+excel-model validate --spec model.yaml
+
+# Describe what a spec would produce
+excel-model describe --spec model.yaml --format text
+```
+
+### Python API
+
+```python
+from excel_model.spec_loader import load_spec
+from excel_model.validator import validate_spec
+from excel_model.excel_writer import build_workbook
+from excel_model.config import load_style
+
+spec = load_spec("model.yaml")
+errors = validate_spec(spec)
+assert not errors
+
+style = load_style(None)  # uses bundled defaults
+build_workbook(spec=spec, inputs=None, output_path="model.xlsx", style=style)
+```
+
+## Model Types
+
+| Type | Description |
+|------|-------------|
+| `p_and_l` | Profit & Loss statement |
+| `dcf` | Discounted Cash Flow valuation |
+| `budget_vs_actuals` | Budget vs Actuals comparison |
+| `scenario` | Multi-scenario analysis (Base/Bull/Bear) |
+| `comparison` | Cross-entity comparison |
+
+## Formula Types
+
+21 built-in formula types including `growth_projected`, `pct_of_revenue`, `sum_of_rows`, `subtraction`, `ratio`, `discounted_pv`, `terminal_value`, `npv_sum`, `variance`, `variance_pct`, `constant`, `custom`, and more.
+
+## Configuration
+
+Style config controls Excel formatting (colors, fonts, number formats). A bundled default is included; override with `--style`:
+
+```yaml
+header_fill_hex: "1F3864"
+header_font_color: "FFFFFF"
+font_name: "Calibri"
+font_size: 10
+number_format_currency: '#,##0'
+number_format_percent: '0.0%'
+```
+
+## License
+
+MIT

excel_model-0.1.0/README.md

@@ -0,0 +1,79 @@
+# excel-model
+
+YAML-driven Excel financial model generator.
+
+Build professional financial models (P&L, DCF, Budget vs Actuals, Scenario Analysis) from declarative YAML specs. Generates `.xlsx` workbooks with named ranges, styled sheets, and Excel formulas using openpyxl.
+
+## Installation
+
+```bash
+pip install excel-model
+```
+
+Or for development:
+
+```bash
+pixi install
+```
+
+## Quick Start
+
+### CLI
+
+```bash
+# Build a P&L model
+excel-model build --spec model.yaml --output model.xlsx --mode batch
+
+# Validate a spec
+excel-model validate --spec model.yaml
+
+# Describe what a spec would produce
+excel-model describe --spec model.yaml --format text
+```
+
+### Python API
+
+```python
+from excel_model.spec_loader import load_spec
+from excel_model.validator import validate_spec
+from excel_model.excel_writer import build_workbook
+from excel_model.config import load_style
+
+spec = load_spec("model.yaml")
+errors = validate_spec(spec)
+assert not errors
+
+style = load_style(None)  # uses bundled defaults
+build_workbook(spec=spec, inputs=None, output_path="model.xlsx", style=style)
+```
+
+## Model Types
+
+| Type | Description |
+|------|-------------|
+| `p_and_l` | Profit & Loss statement |
+| `dcf` | Discounted Cash Flow valuation |
+| `budget_vs_actuals` | Budget vs Actuals comparison |
+| `scenario` | Multi-scenario analysis (Base/Bull/Bear) |
+| `comparison` | Cross-entity comparison |
+
+## Formula Types
+
+21 built-in formula types including `growth_projected`, `pct_of_revenue`, `sum_of_rows`, `subtraction`, `ratio`, `discounted_pv`, `terminal_value`, `npv_sum`, `variance`, `variance_pct`, `constant`, `custom`, and more.
+
+## Configuration
+
+Style config controls Excel formatting (colors, fonts, number formats). A bundled default is included; override with `--style`:
+
+```yaml
+header_fill_hex: "1F3864"
+header_font_color: "FFFFFF"
+font_name: "Calibri"
+font_size: 10
+number_format_currency: '#,##0'
+number_format_percent: '0.0%'
+```
+
+## License
+
+MIT

excel_model-0.1.0/excel_model/__init__.py

@@ -0,0 +1 @@
+"""excel_model — Excel financial model builder."""

excel_model-0.1.0/excel_model/cli.py

@@ -0,0 +1,261 @@
+"""CLI entry point for excel-model."""
+import json
+import sys
+from pathlib import Path
+
+import click
+
+from excel_model.config import load_style
+from excel_model.exceptions import StyleConfigError
+
+
+@click.group()
+def main() -> None:
+    """YAML-driven Excel financial model generator."""
+
+
+@main.command()
+@click.option("--spec", required=True, type=click.Path(exists=True), help="Path to model spec YAML")
+@click.option("--output", required=True, type=click.Path(), help="Path for output .xlsx file")
+@click.option("--style", required=False, type=click.Path(exists=True), help="Path to style config YAML (uses bundled defaults if omitted)")
+@click.option("--data", required=False, type=click.Path(exists=True), help="Path to input data file")
+@click.option("--mode", required=True, type=click.Choice(["batch", "interactive"]), help="batch = JSON to stdout; interactive = verbose narrative")
+def build(spec: str, output: str, style: str | None, data: str | None, mode: str) -> None:
+    """Build an Excel financial model from a YAML spec."""
+    def emit_error(message: str) -> None:
+        if mode == "batch":
+            click.echo(json.dumps({"status": "error", "message": message}))
+        else:
+            click.echo(f"ERROR: {message}", err=True)
+        sys.exit(1)
+
+    def emit_info(message: str) -> None:
+        if mode == "interactive":
+            click.echo(message)
+
+    # Load spec
+    emit_info(f"Loading model spec: {spec}")
+    try:
+        from excel_model.spec_loader import load_spec
+        loaded_spec = load_spec(spec)
+    except (FileNotFoundError, ValueError, KeyError) as e:
+        emit_error(f"Failed to load spec: {e}")
+        return  # unreachable, but keeps type checker happy
+
+    # Validate spec
+    emit_info("Validating model spec...")
+    from excel_model.validator import validate_spec
+    errors = validate_spec(loaded_spec)
+    if errors:
+        emit_error("Spec validation failed:\n" + "\n".join(f"  - {e}" for e in errors))
+    emit_info(f"  Model type: {loaded_spec.model_type}")
+    emit_info(f"  Title: {loaded_spec.title}")
+    emit_info(f"  Currency: {loaded_spec.currency}")
+    emit_info(f"  Periods: {loaded_spec.n_history_periods} history + {loaded_spec.n_periods} projection ({loaded_spec.granularity})")
+    emit_info(f"  Assumptions: {len(loaded_spec.assumptions)}")
+    emit_info(f"  Line items: {len(loaded_spec.line_items)}")
+
+    # Load style
+    emit_info(f"Loading style config: {style or '(bundled defaults)'}")
+    try:
+        loaded_style = load_style(style)
+    except StyleConfigError as e:
+        emit_error(f"Failed to load style config: {e}")
+        return
+
+    # Load input data (optional)
+    inputs = None
+    if data:
+        emit_info(f"Loading input data: {data}")
+        try:
+            from excel_model.loader import load
+            value_cols = list(loaded_spec.inputs.value_cols.values())
+            inputs = load(
+                source_path=data,
+                period_col=loaded_spec.inputs.period_col,
+                value_cols=value_cols,
+                sheet=loaded_spec.inputs.sheet,
+            )
+            emit_info(f"  Loaded {len(inputs.df)} rows")
+
+            from excel_model.validator import validate_inputs_against_spec
+            input_errors = validate_inputs_against_spec(loaded_spec, inputs)
+            if input_errors:
+                emit_error("Input data validation failed:\n" + "\n".join(f"  - {e}" for e in input_errors))
+        except (FileNotFoundError, ValueError) as e:
+            emit_error(f"Failed to load input data: {e}")
+
+    # Build workbook
+    emit_info("Building workbook...")
+    try:
+        from excel_model.excel_writer import build_workbook
+        build_workbook(spec=loaded_spec, inputs=inputs, output_path=output, style=loaded_style)
+    except Exception as e:
+        emit_error(f"Failed to build workbook: {e}")
+
+    output_path = str(Path(output).resolve())
+    emit_info(f"Workbook saved to: {output_path}")
+
+    if mode == "batch":
+        click.echo(json.dumps({"status": "ok", "output": output_path}))
+
+
+@main.command()
+@click.option("--spec", required=True, type=click.Path(exists=True), help="Path to model spec YAML")
+@click.option("--data", required=False, type=click.Path(exists=True), help="Optional input data file to validate column mapping")
+def validate(spec: str, data: str | None) -> None:
+    """Validate a model spec YAML file."""
+    # Load spec
+    try:
+        from excel_model.spec_loader import load_spec
+        loaded_spec = load_spec(spec)
+    except (FileNotFoundError, ValueError, KeyError) as e:
+        click.echo(f"ERROR: {e}")
+        sys.exit(1)
+
+    # Validate spec
+    from excel_model.validator import validate_spec
+    errors = validate_spec(loaded_spec)
+
+    # Optionally validate input data columns
+    if data:
+        try:
+            from excel_model.loader import load
+            value_cols = list(loaded_spec.inputs.value_cols.values())
+            inputs = load(
+                source_path=data,
+                period_col=loaded_spec.inputs.period_col,
+                value_cols=value_cols,
+                sheet=loaded_spec.inputs.sheet,
+            )
+            from excel_model.validator import validate_inputs_against_spec
+            input_errors = validate_inputs_against_spec(loaded_spec, inputs)
+            errors.extend(input_errors)
+        except (FileNotFoundError, ValueError) as e:
+            errors.append(f"Input data: {e}")
+
+    if errors:
+        for err in errors:
+            click.echo(err)
+        sys.exit(1)
+    else:
+        click.echo("OK")
+
+
+@main.command()
+@click.option("--spec", required=True, type=click.Path(exists=True), help="Path to model spec YAML")
+@click.option("--format", "output_format", required=True, type=click.Choice(["text", "json"]), help="Output format")
+def describe(spec: str, output_format: str) -> None:
+    """Dry-run description of what build would produce."""
+    # Load spec
+    try:
+        from excel_model.spec_loader import load_spec
+        loaded_spec = load_spec(spec)
+    except (FileNotFoundError, ValueError, KeyError) as e:
+        click.echo(f"ERROR: Failed to load spec: {e}", err=True)
+        sys.exit(1)
+
+    # Validate spec
+    from excel_model.validator import validate_spec
+    errors = validate_spec(loaded_spec)
+
+    # Build description
+    from excel_model.time_engine import generate_periods
+    try:
+        periods = generate_periods(
+            start_period=loaded_spec.start_period,
+            n_periods=loaded_spec.n_periods,
+            n_history=loaded_spec.n_history_periods,
+            granularity=loaded_spec.granularity,
+        )
+    except ValueError:
+        periods = []
+
+    # Group assumptions by group
+    assumption_groups: dict[str, list] = {}
+    for a in loaded_spec.assumptions:
+        assumption_groups.setdefault(a.group, []).append(a)
+
+    # Group line items by section
+    sections: dict[str, list] = {}
+    for li in loaded_spec.line_items:
+        sections.setdefault(li.section, []).append(li)
+
+    description = {
+        "model_type": loaded_spec.model_type,
+        "title": loaded_spec.title,
+        "currency": loaded_spec.currency,
+        "granularity": loaded_spec.granularity,
+        "start_period": loaded_spec.start_period,
+        "n_history_periods": loaded_spec.n_history_periods,
+        "n_periods": loaded_spec.n_periods,
+        "total_periods": len(periods),
+        "period_labels": [p.label for p in periods],
+        "metadata": {
+            "preparer": loaded_spec.metadata.preparer,
+            "date": loaded_spec.metadata.date,
+            "version": loaded_spec.metadata.version,
+        },
+        "assumptions_count": len(loaded_spec.assumptions),
+        "assumption_groups": {
+            group: [{"name": a.name, "value": a.value, "format": a.format} for a in assumptions]
+            for group, assumptions in assumption_groups.items()
+        },
+        "line_items_count": len(loaded_spec.line_items),
+        "sections": {
+            section: [{"key": li.key, "label": li.label, "formula_type": li.formula_type} for li in items]
+            for section, items in sections.items()
+        },
+        "scenarios": [{"name": s.name, "label": s.label} for s in loaded_spec.scenarios],
+        "column_groups": [{"key": cg.key, "label": cg.label} for cg in loaded_spec.column_groups],
+        "sheets_to_create": ["Assumptions", "Inputs", "Model"],
+        "validation_errors": errors,
+        "inputs": {
+            "source": loaded_spec.inputs.source,
+            "period_col": loaded_spec.inputs.period_col,
+            "value_cols": dict(loaded_spec.inputs.value_cols),
+        },
+    }
+
+    if output_format == "json":
+        click.echo(json.dumps(description, indent=2))
+    else:
+        click.echo(f"Model: {loaded_spec.title}")
+        click.echo(f"Type:  {loaded_spec.model_type}")
+        click.echo(f"Currency: {loaded_spec.currency}")
+        click.echo()
+        click.echo(f"Periods ({loaded_spec.granularity}):")
+        if loaded_spec.n_history_periods > 0:
+            hist = [p.label for p in periods if p.is_history]
+            click.echo(f"  History ({loaded_spec.n_history_periods}): {', '.join(hist)}")
+        proj = [p.label for p in periods if not p.is_history]
+        click.echo(f"  Projection ({loaded_spec.n_periods}): {', '.join(proj)}")
+        click.echo()
+        click.echo(f"Assumptions ({len(loaded_spec.assumptions)}):")
+        for group, assumptions in assumption_groups.items():
+            click.echo(f"  [{group}]")
+            for a in assumptions:
+                click.echo(f"    {a.name}: {a.value} ({a.format})")
+        click.echo()
+        click.echo(f"Line Items ({len(loaded_spec.line_items)}):")
+        for section, items in sections.items():
+            if section:
+                click.echo(f"  [{section}]")
+            for li in items:
+                marker = " [subtotal]" if li.is_subtotal else (" [total]" if li.is_total else "")
+                click.echo(f"    {li.label.strip()}: {li.formula_type}{marker}")
+        if loaded_spec.scenarios:
+            click.echo()
+            click.echo(f"Scenarios ({len(loaded_spec.scenarios)}):")
+            for s in loaded_spec.scenarios:
+                overrides = ", ".join(f"{k}={v}" for k, v in s.assumption_overrides.items())
+                override_str = f" (overrides: {overrides})" if overrides else ""
+                click.echo(f"  {s.label}{override_str}")
+        if errors:
+            click.echo()
+            click.echo(f"Validation errors ({len(errors)}):")
+            for e in errors:
+                click.echo(f"  - {e}")
+        else:
+            click.echo()
+            click.echo("Validation: OK")

excel_model-0.1.0/excel_model/config.py

@@ -0,0 +1,69 @@
+"""Configuration loading with bundled defaults and deep-merge."""
+from importlib import resources
+from pathlib import Path
+
+import yaml
+
+from excel_model.exceptions import StyleConfigError
+from excel_model.style import StyleConfig
+
+
+def _load_default_style_yaml() -> dict:
+    """Load the bundled default style config."""
+    ref = resources.files("excel_model") / "defaults" / "default_style.yaml"
+    return yaml.safe_load(ref.read_text(encoding="utf-8"))
+
+
+def _deep_merge(base: dict, override: dict) -> dict:
+    """Recursively merge override into base. Override values win."""
+    result = dict(base)
+    for key, value in override.items():
+        if key in result and isinstance(result[key], dict) and isinstance(value, dict):
+            result[key] = _deep_merge(result[key], value)
+        else:
+            result[key] = value
+    return result
+
+
+def load_style(style_path: str | None) -> StyleConfig:
+    """Load StyleConfig from YAML, deep-merged with bundled defaults.
+
+    If style_path is None, returns the bundled defaults only.
+    If style_path is provided, user overrides are merged on top of defaults.
+    """
+    defaults = _load_default_style_yaml()
+
+    if style_path is not None:
+        p = Path(style_path)
+        if not p.exists():
+            raise StyleConfigError(f"Style config not found: {style_path}")
+        with p.open() as f:
+            user_data = yaml.safe_load(f) or {}
+        merged = _deep_merge(defaults, user_data)
+    else:
+        merged = defaults
+
+    required = [
+        "header_fill_hex", "header_font_color", "subtotal_fill_hex", "total_fill_hex",
+        "history_col_fill_hex", "section_header_fill_hex", "font_name", "font_size",
+        "number_format_currency", "number_format_percent",
+        "number_format_integer", "number_format_number",
+    ]
+    missing = [k for k in required if k not in merged]
+    if missing:
+        raise StyleConfigError(f"Style config missing required keys: {missing}")
+
+    return StyleConfig(
+        header_fill_hex=merged["header_fill_hex"],
+        header_font_color=merged["header_font_color"],
+        subtotal_fill_hex=merged["subtotal_fill_hex"],
+        total_fill_hex=merged["total_fill_hex"],
+        history_col_fill_hex=merged["history_col_fill_hex"],
+        section_header_fill_hex=merged["section_header_fill_hex"],
+        font_name=merged["font_name"],
+        font_size=int(merged["font_size"]),
+        number_format_currency=merged["number_format_currency"],
+        number_format_percent=merged["number_format_percent"],
+        number_format_integer=merged["number_format_integer"],
+        number_format_number=merged["number_format_number"],
+    )

excel_model-0.1.0/excel_model/defaults/default_style.yaml

@@ -0,0 +1,12 @@
+header_fill_hex: "1F3864"
+header_font_color: "FFFFFF"
+subtotal_fill_hex: "D6E4F0"
+total_fill_hex: "AED6F1"
+history_col_fill_hex: "F2F2F2"
+section_header_fill_hex: "E8F4FD"
+font_name: "Calibri"
+font_size: 10
+number_format_currency: '#,##0'
+number_format_percent: '0.0%'
+number_format_integer: '#,##0'
+number_format_number: '#,##0.00'

excel_model-0.1.0/excel_model/excel_writer.py

@@ -0,0 +1,65 @@
+"""Orchestrator: build_workbook() — creates the full Excel workbook."""
+from pathlib import Path
+
+from openpyxl import Workbook
+
+from excel_model.loader import InputData
+from excel_model.spec import ModelSpec
+from excel_model.style import StyleConfig
+from excel_model.time_engine import generate_periods
+
+
+def build_workbook(
+    spec: ModelSpec,
+    inputs: InputData | None,
+    output_path: str,
+    style: StyleConfig,
+) -> None:
+    """Build and save a complete Excel workbook from the model spec.
+
+    Creates Assumptions, Inputs, and Model sheets.
+    Dispatches to the appropriate model builder based on spec.model_type.
+    """
+    wb = Workbook()
+    # Remove default sheet
+    if "Sheet" in wb.sheetnames:
+        del wb["Sheet"]
+
+    if spec.model_type == "comparison":
+        # Comparison models don't use time_engine periods
+        from excel_model.models.comparison import build_comparison
+        build_comparison(wb, spec, inputs, style)
+    else:
+        periods = generate_periods(
+            start_period=spec.start_period,
+            n_periods=spec.n_periods,
+            n_history=spec.n_history_periods,
+            granularity=spec.granularity,
+        )
+
+        if spec.model_type == "p_and_l":
+            from excel_model.models.p_and_l import build_p_and_l
+            build_p_and_l(wb, spec, inputs, style, periods)
+
+        elif spec.model_type == "dcf":
+            from excel_model.models.dcf import build_dcf
+            build_dcf(wb, spec, inputs, style, periods)
+
+        elif spec.model_type == "budget_vs_actuals":
+            from excel_model.models.budget_vs_actuals import build_budget_vs_actuals
+            build_budget_vs_actuals(wb, spec, inputs, style, periods)
+
+        elif spec.model_type == "scenario":
+            from excel_model.models.scenario import build_scenario
+            build_scenario(wb, spec, inputs, style, periods)
+
+        elif spec.model_type == "custom":
+            from excel_model.models.p_and_l import build_p_and_l
+            build_p_and_l(wb, spec, inputs, style, periods)
+
+        else:
+            raise ValueError(f"Unknown model_type: {spec.model_type!r}")
+
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    wb.save(str(out))

excel_model-0.1.0/excel_model/exceptions.py

@@ -0,0 +1,21 @@
+"""Custom exception classes for excel-model."""
+
+
+class ExcelModelError(Exception):
+    """Base exception for all excel-model errors."""
+
+
+class SpecValidationError(ExcelModelError):
+    """Raised when a model spec fails validation."""
+
+
+class FormulaError(ExcelModelError):
+    """Raised when a formula cannot be rendered."""
+
+
+class InputDataError(ExcelModelError):
+    """Raised when input data is missing, malformed, or incompatible."""
+
+
+class StyleConfigError(ExcelModelError):
+    """Raised when style configuration is invalid or missing."""