Skip to main content

​
Architecture

The Python library in lib/ handles all mathematical computations. It is intentionally separated from the conversational layer (skills) so that:
  • Every calculation is deterministic — same inputs always produce the same outputs
  • Everything is testable — unit tests validate against Damodaran’s reference spreadsheet
  • No AI in the math — the AI handles conversation; Python handles arithmetic

​
Core modules

ModulePurposeKey functions
dcf_engine.pyFCFF projection, terminal value, discounting, equity bridgedcf_valuation(), fcff_waterfall(), equity_bridge()
cost_of_capital.pyWACC computation (3 methods), beta levering, synthetic ratingswacc_detailed(), wacc_industry_avg(), wacc_distribution()
curve_shapes.py6 convergence curve types for forecast variablesexponential_decay(), s_curve(), linear_fade()
option_value.pyDilution-adjusted Black-Scholes for employee optionsoption_value(), dilution_factor(), black_scholes_call()
failure_rate.pyDefault probability by bond rating or company agefailure_rate_by_rating(), failure_rate_by_age()
rd_converter.pyR&D capitalization into research assetcapitalize_rd()
lease_converter.pyOperating lease to debt conversionconvert_operating_leases()
lookup.pyIndustry and country reference data lookupsget_industry(), get_distribution(), get_country_erp()

​
Utility modules

ModulePurpose
populate_curve_data.pyGenerate 10-year forecast schedules from curve type + start/end values
add_forecast_charts.pyInsert convergence charts into the valuation Excel workbook
upgrade_template_v2.pySchema migrations for the spreadsheet template
check_cache.pyValidate cache integrity (files present, dates, sizes)

​
Standalone execution

The plugin can run the full pipeline without any AI interaction via lucky_pipeline.py: 
python3 lucky_pipeline.py --ticker NVDA --date 2026-03-13 --output runs/NVDA_test/
This triggers company identification, data fetching, LTM computation, WACC, growth assumptions, and DCF — all pure Python math. Output is a completed valuation spreadsheet with JSON results.

​
Testing

All modules are tested against the Almarai example pre-loaded in Damodaran’s fcffsimpleginzu spreadsheet. Additional tests use real NVDA data to verify the SEC EDGAR pipeline end-to-end. 
python -m pytest tests/ -v
Test coverage includes: WACC computation, DCF projection, curve shapes, LTM bridging, last-10-K extraction, failure rates, lease conversion, option valuation, R&D capitalization, and SEC API fetching.