How to Use Exact Decimal Calculations Instead of Float for Financial Computations

The AI-Berkshire repository eliminates floating-point drift by enforcing Python's Decimal type through a centralized high-precision context, ensuring every financial calculation from market-cap verification to valuation ratios remains auditable and reproducible.

Financial analysis requires absolute precision, yet Python's native float type introduces binary representation errors that compound across calculations. The xbtlin/ai-berkshire repository solves this by implementing a rigor-first architecture that replaces floating-point arithmetic with exact decimal calculations. This approach uses a shared Decimal context and conversion helpers to handle market-cap validations, PE ratio computations, and scenario modeling without the rounding drift that ruins audit-level accuracy.

The Floating-Point Problem in Financial Code

Binary floating-point numbers cannot represent common decimal values (like 0.1) exactly, causing microscopic errors that accumulate across multiplication and division. For financial computations involving billions in market capitalization or basis-point-sensitive valuation multiples, these errors produce materially wrong results. The AI-Berkshire codebase avoids this entirely by routing every numeric operation through Python's decimal module with explicit precision controls.

Centralized Decimal Architecture

At the foundation of the toolkit lies a single, high-precision Context configured in tools/financial_rigor.py. This context governs all decimal operations to ensure consistent rounding behavior across the entire codebase.

Context Configuration (Line 28)

The repository initializes a module-level context _CTX with 28-digit precision and banker's rounding:

from decimal import Decimal, Context, ROUND_HALF_EVEN

_CTX = Context(prec=28, rounding=ROUND_HALF_EVEN)

This context is imported and reused by ancillary tools like tools/report_audit.py (see lines 30-34), guaranteeing that the audit utilities apply identical precision standards when cross-validating data points.

The exact() Conversion Helper

Before any arithmetic occurs, raw inputs must become Decimal instances without passing through float conversion. The exact() function at lines 31-38 of financial_rigor.py handles this by casting floats to strings first, bypassing binary-float imprecision:

def exact(value) -> Decimal:
    """Convert any numeric to exact Decimal, avoiding float traps."""
    if isinstance(value, Decimal):
        return value
    if isinstance(value, float):
        return Decimal(str(value))   # cast via string → exact

    return Decimal(str(value))

Critical implementation detail: When given a float, the function converts it to a string representation before creating the Decimal, preventing the intermediate binary-float value from infecting the result.

Performing Context-Aware Arithmetic

All mathematical operations in AI-Berkshire use the centralized context's methods rather than Python's standard operators. This ensures the 28-precision limit and rounding mode apply to every intermediate step.

Market-Cap Verification (Lines 74-104)

The verify_market_cap function demonstrates this pattern at lines 80-82, where price and shares are multiplied using the context:

from tools.financial_rigor import exact, _CTX, Decimal

def verify_market_cap(price, shares, reported_cap, currency="USD"):
    p = exact(price)
    s = exact(shares)
    r = exact(reported_cap)
    
    calculated = _CTX.multiply(p, s)
    deviation = _CTX.subtract(calculated, r)
    # ... deviation analysis continues

Practical Usage Examples

Converting Raw Inputs to Exact Decimals

Use the exact() helper to sanitize inputs from external data sources:

from tools.financial_rigor import exact

price = exact(510)              # int → Decimal('510')

shares = exact(9.11e9)          # float → Decimal('9110000000')

market_cap = exact(4.65e12)     # float → Decimal('4650000000000')

Valuation Ratio Calculations

The verify_valuation function (lines 127-161) computes PE, PB, and dividend yield using context arithmetic:

from tools.financial_rigor import verify_valuation

results = verify_valuation(
    price=510,
    eps=23.5,
    bvps=120,
    dividend=2.4
)

# Implementation detail: PE calculated at lines 127-129 via _CTX.divide

# PB calculated at lines 139-141

# Dividend yield at lines 158-161

Exact Expression Calculator

For ad-hoc calculations, exact_calc (lines 110-124) evaluates string expressions and returns exact results:

from tools.financial_rigor import exact_calc

# Supports scientific notation and standard operators

result = exact_calc('510 * 9.11e9')

# Returns: Decimal('4.6401E+12') without float intermediate

The function validates the expression syntax, evaluates it with restricted eval(), and passes the result through exact() before returning.

Three-Scenario Valuation Modeling

The DCF-style scenario analyzer at lines 442-466 wraps all growth rates and multiples with exact() before entering the compound-growth loop (lines 664-666):

from tools.financial_rigor import three_scenario_valuation

three_scenario_valuation(
    current_price=510,
    current_eps=23.5,
    shares_billion=9.11,
    growth_optimistic=0.20,
    growth_neutral=0.10,
    growth_pessimistic=0.05,
    pe_optimistic=30,
    pe_neutral=20,
    pe_pessimistic=15,
    years=3,
    currency="HKD"
)

All intermediate future EPS values and terminal valuations are calculated as Decimal objects within the shared context.

Audit Tool Integration

The report_audit.py utility (line 201 in cross_validate) uses the same _CTX and exact() imports to compare extracted financial data against calculated benchmarks. When the audit tool calculates deviations between reported and computed market caps, it relies on the identical context configuration defined in financial_rigor.py, ensuring cross-tool consistency.

Summary

• Never use raw floats for financial inputs in the AI-Berkshire toolkit; always wrap values with exact() to prevent binary representation errors.
• Centralize precision through a module-level Context (28 digits, ROUND_HALF_EVEN) accessed via _CTX in tools/financial_rigor.py.
• Use context methods (_CTX.multiply, _CTX.divide, _CTX.add) rather than standard operators to enforce rounding rules at every calculation step.
• Maintain cross-file consistency by importing the same decimal configuration into ancillary modules like report_audit.py for audit-level validation.

Frequently Asked Questions

Why is Decimal better than float for financial calculations?

Floating-point numbers use binary fractions that cannot exactly represent decimal values like 0.1 or 0.01, introducing tiny errors that accumulate across operations. Python's Decimal type stores numbers as base-10 digits, allowing exact representation of monetary values and configurable precision for intermediate calculations.

How does the exact() function prevent precision loss?

The exact() function at lines 31-38 of financial_rigor.py converts floats to Decimal by first casting them to strings. This avoids the intermediate step where Python would otherwise convert the float to its exact binary value (which already contains representation error) before creating the Decimal. Integers and strings are converted directly to Decimal without float intermediates.

What precision level does the AI-Berkshire repository use?

The codebase sets a precision of 28 significant digits (line 28 in financial_rigor.py) with ROUND_HALF_EVEN (banker's rounding). This exceeds the requirements for standard financial reporting while preventing excessive memory usage from arbitrary-precision arithmetic.

Can I mix Decimal and float in these calculations?

No. The repository strictly separates the two types. All functions in financial_rigor.py convert inputs to Decimal immediately via exact(), and arithmetic operations use the _CTX methods. Mixing types would force Python to cast Decimals to floats, destroying precision. Always ensure every operand is wrapped with exact() before entering the calculation chain.

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