Handle VTL Number type correctly with tolerance-based comparisons. Docs updates

[javihern98]

Summary

This PR implements tolerance-based comparisons for floating-point numbers in VTL, addressing issue #457, and adds environment variable documentation for issue #458.

Float64 Precision Rationale

IEEE 754 float64 (double precision) has 52 mantissa bits (53 effective with implicit leading 1):

Property	Value	Meaning
log10(2^53)	≈ 15.95	Maximum significant decimal digits
DBL_DIG	15	Guaranteed decimal digits for round-trip (decimal → float64 → decimal)
DBL_DECIMAL_DIG	17	Digits needed for exact float64 → decimal → float64 round-trip

The valid range for significant digits is 6–15, where:

• 6 is the minimum practical precision (coarse tolerance)
• 15 is the maximum guaranteed precision for float64 — beyond this, representation noise appears

Changes

New Environment Variables

Two new environment variables control the behavior:

1. COMPARISON_ABSOLUTE_THRESHOLD - Controls tolerance for comparison operators

   • Default: 15 (significant digits, the maximum guaranteed precision for float64)
   • Range: 6-15
   • Set to -1 to disable tolerance (exact comparison, may trigger errors or extra decimals not needed)

2. OUTPUT_NUMBER_SIGNIFICANT_DIGITS - Controls CSV output formatting

   • Same values as above
   • Controls float_format parameter in pandas to_csv

Tolerance Algorithm

Relative tolerance is calculated as: 0.5 * 10^(-(N-1)) where N = significant digits

For the default of 15 significant digits:

• Relative tolerance = 5e-15
• Absolute tolerance = relative_tolerance × max(|a|, |b|)

This is the most conservative setting that still filters floating-point precision artifacts, using the full guaranteed precision of float64.

Modified Operators

Standard Comparison Operators (Comparison.py):

• Equal (=)
• NotEqual (<>)
• GreaterEqual (>=) — equality checked before strict >
• LessEqual (<=) — equality checked before strict <
• Between

Hierarchical Ruleset Operators (HROperators.py):

• HREqual
• HRGreaterEqual — equality checked before strict >
• HRLessEqual — equality checked before strict <

Output Formatting

CSV output now uses float_format="%.{N}g" to limit floating-point precision in output files.

Documentation (Issue #458)

New docs/environment_variables.rst page documenting:

• Number handling variables (COMPARISON_ABSOLUTE_THRESHOLD, OUTPUT_NUMBER_SIGNIFICANT_DIGITS)
• S3/AWS configuration variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION, AWS_ENDPOINT_URL)
• Usage examples for each scenario
• Float64 precision rationale

Added to the docs toctree in docs/index.rst.

Claude Code Instructions

New CLAUDE.md file with project-specific instructions for Claude Code, derived from .github/copilot-instructions.md.

Test Coverage

• Number handling tests refactored to pytest with @pytest.mark.parametrize
• S3 mock tests updated to expect float_format parameter in to_csv calls
• All 3463 tests passing
• Updated test_DEMO1 expected output: now returns 4 rows with real imbalances (filters 35 floating-point artifacts)
• Strict typing (Union[int, float]) on _numbers_less_equal and _numbers_greater_equal

Breaking Changes

This change affects comparison results for floating-point numbers. Users can:

Goal	Setting
Disable tolerance (exact comparisons)	COMPARISON_ABSOLUTE_THRESHOLD=-1
More lenient tolerance	COMPARISON_ABSOLUTE_THRESHOLD=10 (tolerance ~5e-10)
Strictest tolerance (default)	COMPARISON_ABSOLUTE_THRESHOLD=15 (~5e-15, full float64 precision)

Closes #457
Closes #458

[javihern98]

Do not merge automatically this branch, I will merge it when Suite team have checked also the changes