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

The three_scenario_valuation function defined at line 320 of 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 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 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:

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:

target_price = _CTX.multiply(future_eps, target_pe)

Percentage Change and Output

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

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 inside a notebook or script:

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:

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 (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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}