How to Use Three-Scenario Valuation for Target Price Calculation in Python

The three-scenario valuation model in ai-berkshire uses exact decimal arithmetic to project optimistic, base, and pessimistic target prices by compounding EPS growth rates and applying scenario-specific PE multiples over a configurable time horizon.

The three-scenario valuation method helps investors model bull, base, and bear cases for equity valuation. In the xbtlin/ai-berkshire repository, this methodology is implemented as a high-precision Python utility in tools/financial_rigor.py. This guide explains how to use the three_scenario_valuation function to calculate target prices with deterministic, audit-friendly arithmetic.

Architecture of the Three-Scenario Valuation Model

Exact Decimal Engine

To prevent floating-point drift, the implementation uses Python's decimal.Decimal type with a high-precision context. The global _CTX variable defined at lines 28-29 in tools/financial_rigor.py is configured to 28 significant digits. This ensures that EPS projections and target price calculations remain deterministic and reproducible across different hardware platforms.

Core Calculation Logic

The valuation algorithm performs three sequential steps for each scenario:

1. EPS Projection: Compounds the current EPS by (1 + growth_rate) ^ years (see the loop at lines 63-66)
2. Target Price Derivation: Multiplies projected EPS by the scenario-specific PE multiple using the formula target_price = projected_eps × target_pe (line 66)
3. Upside/Downside Calculation: Compares the target price against the current market price to compute percentage changes

The function iterates over the three scenarios—optimistic, base, and pessimistic—using the same projection logic for each case (lines 46-61).

Running the Three-Scenario Valuation

Command-Line Interface

The tool exposes a three-scenario sub-command via the CLI. The argument parser at lines 26-36 accepts all necessary inputs including growth rates and PE multiples as space-separated lists.

python3 tools/financial_rigor.py three-scenario \
    --price 510 \
    --eps 23.5 \
    --shares 9.11 \
    --growth 0.15 0.08 0.00 \
    --pe 25 20 15 \
    --years 3 \
    --currency HKD

Parameter reference:

• --price: Current market price per share
• --eps: Current trailing twelve-month EPS
• --shares: Total shares outstanding in billions
• --growth: Three decimal growth rates (optimistic, base, pessimistic)
• --pe: Three target PE multiples corresponding to each scenario
• --years: Projection horizon (default 3 years)
• --currency: Optional currency label for output formatting

Python API Integration

Import the function directly for use in notebooks or automated pipelines:

from tools.financial_rigor import three_scenario_valuation

three_scenario_valuation(
    510,              # current_price

    23.5,             # current_eps

    9.11,             # shares in billions

    0.15, 0.08, 0.0,  # optimistic, base, pessimistic growth

    25, 20, 15,       # optimistic, base, pessimistic PE

    years=3,
    currency="HKD"
)

You can also pass Decimal instances directly if you require extreme precision beyond standard float inputs.

Embedding in Research Workflows

For automated pipelines, load parameters from JSON configuration files:

import json
from tools.financial_rigor import three_scenario_valuation

config = {
    "price": 510,
    "eps": 23.5,
    "shares": 9.11,
    "growth": [0.15, 0.08, 0.0],
    "pe": [25, 20, 15],
    "years": 3,
    "currency": "HKD"
}

three_scenario_valuation(
    config["price"],
    config["eps"],
    config["shares"],
    *config["growth"],
    *config["pe"],
    years=config["years"],
    currency=config["currency"],
)

Output Format and Interpretation

The function prints a formatted table (lines 56-71) displaying:

• Scenario name (乐观/中性/悲观 or Bull/Base/Bear)
• Annual growth rate and target PE multiple
• Projected EPS after compounding
• Calculated target price
• Percentage price change versus current price

The final output includes a confirmation message (lines 72-74) verifying that all calculations used exact decimal arithmetic, ensuring results are auditable and reproducible.

Summary

• The three-scenario valuation model lives in tools/financial_rigor.py and implements deterministic decimal arithmetic via the _CTX context manager
• It calculates target prices by compounding EPS over n years then applying scenario-specific PE multiples
• Available as both a CLI tool (three-scenario sub-command) and importable Python function
• Accepts growth rates and PE multiples for optimistic, base, and pessimistic cases in a single call
• Outputs audit-ready calculations suitable for financial research workflows

Frequently Asked Questions

Why does the three-scenario valuation use Decimal instead of float?

The implementation uses decimal.Decimal with a 28-digit precision context to eliminate floating-point rounding errors. This ensures that EPS projections and target price calculations are deterministic and match exactly across different computing environments, which is critical for financial auditing and reproducible research.

How are the growth rates applied in the calculation?

For each scenario, the current EPS is multiplied by (1 + growth_rate) for each year in the projection horizon. The loop at lines 63-66 in tools/financial_rigor.py performs this compounding operation using exact decimal arithmetic to derive the projected EPS before applying the PE multiple.

Can I use this valuation method for currencies other than HKD?

Yes. The --currency parameter accepts any string label (e.g., USD, EUR, CNY) and only affects the display output. The underlying calculations are currency-agnostic, though you should ensure that the price, EPS, and shares inputs use consistent units for the target market.

What is the significance of the shares parameter if the output is price per share?

The shares parameter (provided in billions) is included in the function signature for consistency with other valuation tools in the ai-berkshire toolkit. In the three-scenario valuation specifically, the calculation focuses on per-share metrics (EPS × PE), so the total shares outstanding do not affect the target price computation but are displayed for reference in the output table.

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