> ## Documentation Index
> Fetch the complete documentation index at: https://valuation-101.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Python Library Overview

> The deterministic math engine behind Valuation101 — 12 pure Python modules, no AI dependencies.

## 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

| Module                                       | Purpose                                                        | Key functions                                                   |
| -------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------- |
| [dcf\_engine.py](/docs/lib/dcf-engine)            | FCFF projection, terminal value, discounting, equity bridge    | `dcf_valuation()`, `fcff_waterfall()`, `equity_bridge()`        |
| [cost\_of\_capital.py](/docs/lib/cost-of-capital) | WACC computation (3 methods), beta levering, synthetic ratings | `wacc_detailed()`, `wacc_industry_avg()`, `wacc_distribution()` |
| [curve\_shapes.py](/docs/lib/curve-shapes)        | 6 convergence curve types for forecast variables               | `exponential_decay()`, `s_curve()`, `linear_fade()`             |
| [option\_value.py](/docs/lib/option-value)        | Dilution-adjusted Black-Scholes for employee options           | `option_value()`, `dilution_factor()`, `black_scholes_call()`   |
| [failure\_rate.py](/docs/lib/failure-rate)        | Default probability by bond rating or company age              | `failure_rate_by_rating()`, `failure_rate_by_age()`             |
| [rd\_converter.py](/docs/lib/adjustments)         | R\&D capitalization into research asset                        | `capitalize_rd()`                                               |
| [lease\_converter.py](/docs/lib/adjustments)      | Operating lease to debt conversion                             | `convert_operating_leases()`                                    |
| [lookup.py](/docs/lib/data-loader)                | Industry and country reference data lookups                    | `get_industry()`, `get_distribution()`, `get_country_erp()`     |

## Utility modules

| Module                   | Purpose                                                                |
| ------------------------ | ---------------------------------------------------------------------- |
| populate\_curve\_data.py | Generate 10-year forecast schedules from curve type + start/end values |
| add\_forecast\_charts.py | Insert convergence charts into the valuation Excel workbook            |
| upgrade\_template\_v2.py | Schema migrations for the spreadsheet template                         |
| check\_cache.py          | Validate cache integrity (files present, dates, sizes)                 |

## Standalone execution

The plugin can run the full pipeline without any AI interaction via `lucky_pipeline.py`:

```bash theme={null}
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.

```bash theme={null}
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.