How to Perform Three-Scenario Valuation Using financial_rigor.py: A Complete Guide

The three_scenario_valuation function in tools/financial_rigor.py computes optimistic, neutral, and pessimistic price targets by compounding EPS growth over a specified period and applying scenario-specific PE multiples.

The xbtlin/ai-berkshire repository provides a Financial Rigor Toolkit designed for reproducible equity analysis. The three_scenario_valuation routine sits at the heart of this toolkit, offering a deterministic way to model bull, base, and bear cases using exact decimal arithmetic to eliminate floating-point drift.

Core Architecture of the Valuation Model

The implementation prioritizes numerical precision and transparent scenario modeling. Unlike standard floating-point calculations that accumulate rounding errors, this tool uses a dedicated decimal context for every operation.

Exact Decimal Arithmetic

All monetary and ratio calculations rely on the exact helper function (defined around lines 31–38) and a shared _CTX context (line 28). This context enforces a fixed precision and rounding mode, ensuring that EPS projections and target prices remain identical across repeated runs. The exact helper converts raw inputs like share prices and growth rates into Decimal objects before any mathematics occurs.

Scenario Definition Structure

The function internally defines three scenarios as a list of tuples containing the scenario name, annual growth rate, and target PE multiple (lines 33–37). These map to:

• Optimistic: Higher growth assumptions with premium PE multiples
• Neutral: Moderate growth aligned with historical averages
• Pessimistic: Conservative or zero growth with compressed multiples

How to Use three_scenario_valuation in Python

Import the function directly from the tools module and supply current market data along with your three sets of assumptions.

from tools.financial_rigor import three_scenario_valuation

# Current market data

price = 510                # Current share price

eps   = 23.5               # Current EPS

shares = 9.11              # Total shares (in billions)

# Growth rates for optimistic, neutral, pessimistic (15%, 8%, 0%)

growth = [0.15, 0.08, 0.00]

# Target PE multiples for each scenario

pe = [25, 20, 15]

# Run the valuation

three_scenario_valuation(
    current_price=price,
    current_eps=eps,
    shares_billion=shares,
    growth_optimistic=growth[0],
    growth_neutral=growth[1],
    growth_pessimistic=growth[2],
    pe_optimistic=pe[0],
    pe_neutral=pe[1],
    pe_pessimistic=pe[2],
    years=3,
    currency="HKD"
)

The function outputs a formatted table showing projected EPS, target prices, and percentage changes relative to the current market price.

Command-Line Interface Usage

The repository exposes this functionality via the three-scenario sub-parser (lines 13–24 in the CLI block). This allows rapid valuation without writing Python scripts.

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

When executed, the CLI forwards these arguments to the core three_scenario_valuation function (lines 41–45), producing identical output to the Python API.

Step-by-Step Calculation Process

Understanding the internal mechanics helps validate your assumptions and debug outliers.

Future EPS Projection

For each scenario, the function compounds the current EPS over the specified timeframe (default 3 years) using the scenario-specific growth rate (lines 51–53). The calculation uses exact multiplication: future_eps = current_eps * (1 + growth_rate) ** years.

Target Price Calculation

The projected EPS is multiplied by the scenario's target PE multiple to derive the intrinsic value (line 54). This follows the formula: target_price = projected_eps * pe_multiple.

Result Presentation

The function prints a formatted table (lines 44–58) including:

• Scenario name (乐观/中性/悲观)
• Annual growth percentage
• Target PE multiple
• Projected EPS
• Target price in the specified currency
• Percentage change from current price

All values maintain the decimal precision established by the _CTX context.

Integrating into Research Workflows

You can embed this valuation routine into larger analysis pipelines. Here is a pattern for generating automated research reports:

def generate_report(ticker):
    # ... fetch latest price, EPS, and share count ...

    three_scenario_valuation(
        current_price=price,
        current_eps=eps,
        shares_billion=shares,
        growth_optimistic=0.12,
        growth_neutral=0.06,
        growth_pessimistic=0.00,
        pe_optimistic=30,
        pe_neutral=22,
        pe_pessimistic=18,
        years=5,
        currency="USD"
    )
    # Append results to your markdown report

This approach leverages the exact-decimal engine to ensure that your valuation outputs remain consistent across different environments and Python versions.

Summary

• three_scenario_valuation in tools/financial_rigor.py implements a three-case valuation model using exact decimal arithmetic to prevent floating-point errors.
• The function requires current market data (price, EPS, shares) plus three sets of growth assumptions and PE targets.
• Exact calculations are ensured through the exact helper and _CTX context (lines 28–38).
• You can invoke the model programmatically via Python import or interactively through the three-scenario CLI command.
• The output displays projected EPS, target prices, and upside/downside percentages for optimistic, neutral, and pessimistic scenarios.

Frequently Asked Questions

What precision does the three-scenario valuation use for calculations?

The function uses Python's Decimal type with a shared context _CTX (line 28) that provides fixed precision and rounding modes. All inputs pass through the exact helper (lines 31–38) to ensure reproducible results without floating-point drift.

Can I change the forecast period from the default 3 years?

Yes. Pass the years parameter to three_scenario_valuation or use the --years flag in the CLI. The function compounds EPS growth using this horizon for all three scenarios.

Where is the CLI entry point defined in the source code?

The three-scenario sub-parser is defined in tools/financial_rigor.py around lines 13–24. This block configures argument parsing for price, EPS, growth rates, and PE multiples, then forwards them to the core valuation function at lines 41–45.

How does the function handle share count in billions?

The shares_billion parameter accepts the total share count expressed in billions (e.g., 9.11 for 9.11 billion shares). The function uses this for display purposes and any per-share calculations within the exact decimal context.

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