# Three-Scenario Valuation Method in `financial_rigor.py`: Exact-Decimal Price Projections

> Discover the three-scenario valuation method in financial_rigor.py. Project share prices with exact-decimal EPS and configurable P/E multiples for optimistic, neutral, and pessimistic growth.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: deep-dive
- Published: 2026-07-25

---

**The `three_scenario_valuation` function defined at line 320 of [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) projects target share prices under optimistic, neutral, and pessimistic growth assumptions by compounding exact-decimal EPS over a configurable horizon and applying scenario-specific P/E multiples.**

The `xbtlin/ai-berkshire` repository provides a suite of quantitative tools for reproducible equity analysis. Among them, the **three-scenario valuation method in [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py)** offers a disciplined way to map varying growth expectations into forward price targets. Analysts supply a current stock price, EPS, share count, three distinct growth rates, and three target P/E multiples; the routine returns an audit-ready table of bull, base, and bear valuations.

## How `three_scenario_valuation` Works

The core routine is implemented in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) at line 320. It accepts the current market price, current EPS, total shares in billions, three annual EPS growth rates, three target P/E multiples, a projection horizon, and an optional currency label. Every numeric input is converted to a `Decimal` instance before the scenario loop begins.

### Exact-Decimal Initialization

To prevent floating-point drift, the module defines a high-precision `_CTX` context at line 28 using Python’s `decimal` module with 28-digit precision. A helper named `exact()` at line 31 coerces raw floats and strings into `Decimal` objects. As noted in the source at line 60, this guarantees audit-able, reproducible arithmetic across all subsequent steps.

### EPS Compounding and Target Price

The function iterates over the optimistic, neutral, and pessimistic scenarios. For each scenario, it compounds the starting EPS year by year using the supplied growth rate:

```python
future_eps = eps
for _ in range(years):
    future_eps = _CTX.multiply(future_eps, _CTX.add(Decimal("1"), growth))

```

After the loop, the projected EPS is multiplied by the scenario-specific target P/E to derive the target share price:

```python
target_price = _CTX.multiply(future_eps, target_pe)

```

### Percentage Change and Output

Finally, the deviation from the current price is expressed as a percentage:

```python
change = float(target_price - p) / float(p) * 100

```

The routine prints a tidy table with the scenario name, annual growth rate, target P/E, projected EPS, target price (with optional currency), and percentage change relative to today.

## Python API Example

You can import `three_scenario_valuation` directly from [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) inside a notebook or script:

```python
from tools.financial_rigor import three_scenario_valuation

# Example: 100 HKD price, EPS 2.5, 9.5 billion shares

three_scenario_valuation(
    current_price=100,
    current_eps=2.5,
    shares_billion=9.5,
    growth_optimistic=0.15,   # 15% annual growth

    growth_neutral=0.08,      # 8% annual growth

    growth_pessimistic=0.00,  # 0% growth

    pe_optimistic=25,
    pe_neutral=20,
    pe_pessimistic=15,
    years=3,
    currency="HKD"
)

```

## CLI Usage

The file also registers a `three-scenario` sub-command, so the same analysis can be run directly from the terminal:

```bash
python3 tools/financial_rigor.py three-scenario \
    --price 100 \
    --eps 2.5 \
    --shares 9.5 \
    --growth 0.15 0.08 0.00 \
    --pe 25 20 15 \
    --years 3 \
    --currency HKD

```

The command prints the identical formatted table, making it easy to integrate into automated valuation pipelines.

## Why Exact-Decimal Arithmetic Matters

Multi-year financial projections repeatedly multiply growth factors, a process where 64-bit floats can introduce imperceptible errors that cascade into cent-level discrepancies. According to the `xbtlin/ai-berkshire` source code, the `three_scenario_valuation` function mitigates this by routing every operation through a 28-digit `decimal.Context`. This design ensures that analysts, auditors, and automated systems all observe the same penny-exact outputs regardless of hardware or Python version.

## Summary

- The `three_scenario_valuation` function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) (line 320) implements a transparent bull/base/bear price-target framework.
- It requires current price, EPS, shares outstanding, three growth rates, three target P/E multiples, and an optional projection horizon (default 3 years) plus currency label.
- All intermediate math uses Python’s `decimal` module via a 28-digit precision context to eliminate floating-point drift.
- Future EPS is compounded annually per scenario, converted to a target price via the scenario P/E, and compared to the current price as a percentage change.
- Results are exposed through both a Python API and a `three-scenario` CLI command for flexible workflow integration.

## Frequently Asked Questions

### What does the three-scenario valuation method in [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) do?

It computes forward-looking target stock prices under optimistic, neutral, and pessimistic assumptions. The function compounds current EPS by a scenario-specific annual growth rate, applies a matching target P/E multiple, and expresses the resulting target price as a percentage change from the current market price.

### How does `three_scenario_valuation` prevent rounding errors?

The module uses a `decimal.Context` named `_CTX` configured to 28-digit precision (line 28) and an `exact()` helper (line 31) to convert all inputs into `Decimal` objects. Every multiplication and addition inside the EPS compounding loop routes through this context, ensuring penny-exact reproducibility across runs.

### What parameters does the `three_scenario_valuation` function accept?

It accepts `current_price`, `current_eps`, `shares_billion`, `growth_optimistic`, `growth_neutral`, `growth_pessimistic`, `pe_optimistic`, `pe_neutral`, and `pe_pessimistic`. Optional arguments include `years` (default 3) and `currency`. All numeric values are coerced to exact decimals before any scenario math occurs.

### Can the three-scenario model be executed from the command line?

Yes. [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) exposes a `three-scenario` sub-command that mirrors the Python API. You can pass flags such as `--price`, `--eps`, `--growth`, and `--pe` to generate the same formatted output table directly in the terminal.