V0 Changelog#

0.61.1 (2026-07-28)#

Fixed#

  • The summary sheet’s statistics table now shows one column per configured benchmark (labeled by ticker) instead of a single Benchmark column, so a multi-benchmark run ("SPY,QQQ") compares the portfolio against every benchmark side by side — matching the benchmark_comparison sheet. Portfolio-relative metrics (Alpha, Information Ratio, Tracking Error) remain N/A in the benchmark columns, and a single-benchmark run is unchanged except that the column is now labeled with the ticker.

  • The stats table keeps exactly two empty columns of separation from the annual-returns table; the gap is now computed from the stats-table width so it stays correct as benchmark columns are added.

  • The portfolio-info block (Start Date / End Date / Years) is placed below the stats table instead of at a fixed row 18. It previously overlapped the last two metric rows (Max Drawdown Date, Alpha), hiding them; both rows are now visible, and an extra benchmark column no longer collides with the info block.

0.61.0 (2026-07-28)#

Added#

  • Multiple benchmarks. benchmark_file_name now accepts a comma-separated list (e.g. "SPY,QQQ,IWM"); the first entry is the primary (comparison) benchmark used for Alpha / Information Ratio / Tracking Error, and every listed benchmark is built and carried through the pipeline. New Configuration.get_benchmark_file_names() / get_primary_benchmark() (backed by the module-level split_benchmark_file_names) and DataPipelineResult.get_benchmarks() expose the full set additively, while the singular benchmark remains the primary for backward compatibility. A single ticker behaves exactly as before.

  • New performance metrics. PnL (End Balance − Start Balance), Information Ratio (mean(active) / std(active) × √252) and Tracking Error (annualized sample std of the active return), computed against the primary benchmark and surfaced in both the Excel report and the dashboard.

  • Multi-benchmark Excel report. A dedicated benchmark_comparison matrix sheet (metric × [Portfolio, benchmarks…]); the performance/drawdown chart draws one value line and one drawdown fill per benchmark; the portfolio_bench_total_value sheet gains a <ticker>_Value / <ticker>_Returns column pair per benchmark; and the annual-returns table carries one column set per benchmark.

  • Multi-benchmark dashboard. The performance chart, the statistics table (now a metric × [Portfolio, benchmarks…] matrix), the drawdown tab (one fill per benchmark) and the annual-returns tab (one column set per benchmark) all show every configured benchmark. A single benchmark renders exactly as before.

  • Multi-benchmark batch runs. A comma-separated benchmark_file_name in global_defaults or a per-portfolio override no longer breaks a batch: SharedDataPool loads and builds every benchmark, and the ticker-collection pass expands each one. The per-portfolio report labels use the primary benchmark.

Changed#

  • ~44× faster ``run()`` on the bundled 110-ticker × 2836-day dataset (≈17 s → ≈0.4 s), verified bit-exact against the previous engine via the side-by-side A/B test (rebalancing outputs — Commission_df, Shares_df, orders_df, Total_commissions — identical; daily valuation within float tolerance rtol=1e-9, atol=1e-6):

  • New numpy-backed PyArrowBacktesterFast pre-converts the three price tables to dense float64 matrices once in __init__, turning each per-ticker/day price lookup into an O(1) array index instead of a PyArrow filter-and-extract (Opt#1).

  • run() now loops over rebalances and computes each constant-state window’s daily snapshots with a single matrix operation, cutting the Python loop from ~2500 days to ~40 rebalances (Opt#2).

  • ExecutionBroker.execute_rebalance_vectorized computes every target ticker’s diff vectorized and only iterates the tickers that actually trade, reusing the existing commission/slippage models (bit-exact).

  • main(), MultiPortfolioBacktester and BacktestVariationRunner instantiate the fast engine in production; the original PyArrowBacktester and the A/B test are kept as the regression baseline.

Fixed#

  • Annual-returns table (Excel + dashboard): it showed a single, mislabeled "SPY,QQQ_return" column set — the raw benchmark_file_name was used as the column prefix and only the primary benchmark was merged — and carried a junk year_number column. It now shows one correctly-labeled column set per benchmark (per-year CAGR and alpha computed exactly as before) and drops year_number; single-benchmark output is bit-identical.

  • The benchmark_comparison matrix sheet now formats its values by metric (currency / percentage / ratio), matching the summary statistics table, instead of writing raw numbers. The generic data-sheet writer had derived each cell’s format from the column name, which on this sheet is a ticker that matches no metric.

0.60.0 (2026-07-27)#

Fixed#

  • Daily portfolio valuation now uses the configured mark_to_market_price_column instead of the execution price. PyArrowBacktester._record_daily_status was passing _get_execution_price_for_ticker to both calculate_portfolio_value and calculate_weights, so the mark-to-market price table was loaded and filtered on every trading day but never read — the mark_to_market_price_column setting had no effect on any result. A new _get_mark_to_market_price_for_ticker getter is now used for the daily snapshot. Trade execution, commission sizing, and the available-capital calculation continue to use the execution price, so Commission_df, Shares_df, orders_df, and Total_commissions are bit-exact unchanged. This changes the numerical results of existing backtests — Total_Portfolio_Value, Portfolio_Value, Daily_Weights, Returns, and all derived metrics (Sharpe ratio, max drawdown, annualized return, final_total_portfolio_value) shift whenever the mark-to-market column differs from the execution column (e.g. a dividend-and-split-adjusted series vs a split-only-adjusted one).

Changed#

  • Performance and memory, with no change to results (verified bit-exact against the pre-change engine on the bundled dataset — Register_df, Daily_Weights, Commission_df, Shares_df, orders_df, and Total_commissions all identical):

  • Removed the per-date _all_prices_cache from PyArrowBacktester. The main loop visits each trading day exactly once, so the cache never registered a hit; it only accumulated one filtered copy of all three price tables per day, holding ~64 MB of PyArrow buffers alive for the entire run on a 110-ticker × 2836-day backtest (peak memory dropped ~22%). _get_all_prices_for_date now builds the day’s tables fresh and lets them be freed once the day is processed.

  • PortfolioStateManager.calculate_weights accepts an optional pre-computed total_value. _record_daily_status now passes the value it already computed for the daily snapshot instead of having calculate_weights recompute the full portfolio valuation a second time per day.

0.59.0 (2026-06-03)#

Added#

  • Basis-point commission model for crypto and other notional-based fee schedules. New commission_model selector (per_share | basis_points) and commission_basis_points parameters in the Excel General sheet (and in batch global_defaults / template / portfolio overrides), validated by the new BasisPoints value object (range 0–1000 bps) and CommissionModelType enum. The basis-points model prices against the real trade notional via the trade price (1 bp = 0.01%, so 100 = 1%). The default remains per_share, preserving existing behavior. Model selection is dispatched by the new build_commission_model() factory.

Changed#

  • Breaking: CommissionModelInterface.calculate(shares) is now calculate(context), receiving a new CommissionContext (shares + price) value object. All built-in commission models were updated; the unused PercentageCommission.calculate_with_price() method and notional_per_share parameter were removed. Custom external commission models must update their calculate signature accordingly.

  • Excel parameters_format_version bumped to 0.57.0. Configuration files using an older format version are rejected with an “outdated format” message (run kaxanuk.backtest_engine update excel to get the latest template).

Documentation#

  • Removed obsolete references to execution_price from the End User Manual (configuration.rst, excel_workflow.rst, running_from_python.rst). The field was removed in v0.57.0 and is now rejected by BatchConfigParser since v0.58.5; users following the manual no longer see it as a valid parameter.

  • use_cases.rst now points to the public KaxaNuk/Backtest-Engine-Use-Cases repository as the single source of executable examples, mirroring the pattern used by the Data Curator project.

  • end_user_manual/index.rst expanded with an Excel-vs-Python “Choose your workflow” table that helps a new reader pick the right execution path.

  • Main index.rst gained a “What’s new in 0.58.x” section with a TL;DR of breaking changes and headline fixes.

0.58.6 (2026-05-19)#

Fixed#

  • generate_comprehensive_excel_report now restores the date index column on the portfolio_bench_total_value sheet. pd.concat([register_df, benchmark[...]], axis=1) was silently dropping index.name because the two source DataFrames carried different names (register_df.index.name == "date" vs benchmark.index.name == "date_column" from StandardField.DATE.value). Without a name, include_index = dataframe.index.name is not None evaluated False and the writer skipped both the header and every date cell, leaving the sheet with only the value columns. The concat result is now explicitly renamed to "date", mirroring the other data sheets.

0.58.5 (2026-05-13)#

Changed#

  • BatchConfigParser.parse_dict() / parse_file() now reject execution_price in global_defaults with a BatchConfigError pointing to user_column_trade_execution_price. The key was silently ignored since v0.57.0 (when execution_price was removed from the Excel configuration and order execution was wired to StandardField.TRADE_EXECUTION_PRICE exclusively), which let users believe they were configuring the execution price via the batch dict/YAML when in fact only user_column_trade_execution_price was being read. Surfacing the error closes that hidden mismatch and makes the batch path consistent with the Excel path.

0.58.4 (2026-05-13)#

Changed#

  • MultiPortfolioRunner.run() now logs the empty-batch failure via logger.error(...) before raising NoPortfoliosDiscoveredError. The error message appears as a single [ERROR] line in the configured logger format (matching the surrounding [INFO] Discovered 0 portfolio files ... line) instead of only surfacing as a raw Python traceback when callers invoke the runner directly without a top-level try/except BacktestError wrapper like the one in backtest_engine.main().

0.58.3 (2026-05-13)#

Added#

  • NoPortfoliosDiscoveredError exception (subclass of BatchConfigError → ConfigurationError) exported from kaxanuk.backtest_engine.exceptions.

Fixed#

  • MultiPortfolioRunner.run() no longer crashes with an opaque IndexError: list index out of range inside _build_reference_configuration when portfolio_directory is configured but resolves to zero portfolios (empty directory, missing directory, or no files matching the expected format). It now raises NoPortfoliosDiscoveredError with a message that includes the scanned directory and the expected format.

0.58.2 (2026-05-12)#

Fixed#

  • MultiPortfolioBacktester.generate_individual_reports now sets the benchmark DatetimeIndex from the canonical StandardField.DATE column (currently "date_column") instead of the literal string "date" that does not exist in the schema. The old lookup silently fell through and called pd.to_datetime on the integer RangeIndex (0, 1, 2, …), producing timestamps near 1970-01-01 that propagated to every annual-returns row, the Max Drawdown Date of the benchmark, and the embedded chart. Annual returns and Max Drawdown Date for the benchmark now align with the portfolio’s date range. Same fix applied to the register_df lookup for symmetry.

0.58.1 (2026-05-12)#

Fixed#

  • portfolio_drawdown_viz now picks the date_column from the benchmark DataFrame when present, instead of relying on its index. The previous 0.58.0 fix coerced the index to datetime, but when the benchmark comes from a pa.Table.to_pandas() the index is a plain RangeIndex (0, 1, 2, …) and pd.to_datetime interpreted those integers as nanoseconds-since-epoch, leaving every point near 1970-01-01 — the visible vertical line in the embedded Excel charts.

0.58.0 (2026-05-12)#

Breaking Changes#

  • Renamed environment variable KNPC_API_KEY_KAXANUK → KNBE_API_KEY_KAXANUK. Update your Config/.env file accordingly.

Added#

  • arrow_to_pandas_for_analysis() helper in kaxanuk.backtest_engine.modules.type_converters. Converts a pyarrow.Table to a pandas.DataFrame with analysis-friendly dtypes: decimal128/decimal256 columns are coerced to float64 and date32/timestamp columns to datetime64[ns]. Use it when feeding a backtest’s PyArrow result into matplotlib, numpy or scikit-learn.

Fixed#

  • portfolio_drawdown_viz no longer renders a spurious vertical line at 1970-01-01 when the caller passes a benchmark DataFrame that originated from a pa.Table.to_pandas() (object dtype with datetime.date index and decimal.Decimal values). The function now coerces the index and the plotted columns defensively before drawing.

Documentation#

  • Full Sphinx documentation overhaul: real runtime dependencies in docs/requirements.txt (no more MagicMock in signatures), new Backtest Components section covering cost_models, enums, execution, interfaces and orchestrators subpackages, enriched docstrings across the backtest package and the data/portfolio/market pipelines, CLI page rebuilt with intro + summary table + common workflows, and See Also cross-references from load methods to the user guide. Build now finishes with 0 warnings.

  • Fixed two malformed .. deprecated:: directives in portfolio_configuration_service.py so the rendered notice reads “Deprecated since version 0.40.0: Use load_from_file() instead.” instead of the previous garbled output.

  • load_portfolio_from_name and load_portfolio_from_weights are excluded from the Sphinx API reference (still callable from Python for backwards compatibility).

0.57.0 (2026-04-15)#

Breaking Changes#

  • Removed ``execution_price`` Excel configuration field. Order execution now always uses the column named in trade_execution_price_column (internally mapped to StandardField.TRADE_EXECUTION_PRICE). To migrate, run kaxanuk.backtest_engine update excel and delete the execution_price row from your existing Config/backtest_engine_parameters.xlsx if you updated manually.

  • Renamed environment variable KAXANUK_LICENSE_KEY → KNPC_API_KEY_KAXANUK. Update your Config/.env file accordingly.

  • ``MarketDataBundlePyarrow.get_execution_table()`` signature changed. The method no longer accepts an execution_price parameter; it returns the TRADE_EXECUTION_PRICE table directly.

  • Excel template format version bumped from 0.54.0 to 0.56.0. The engine enforces this check at startup — outdated Excels must be regenerated via kaxanuk.backtest_engine update excel.

  • Minimum rebalance dates relaxed from 2 → 1. Users relying on the previous validation for error detection should revisit their portfolio files.

Added#

  • __parameters_format_version__ constant exported from kaxanuk.backtest_engine for tracking Excel schema version independently of the package version.

  • Explicit version-compatibility check at Excel load time: raises ConfigurationHandlerError with a “run update excel” hint when the Excel format is outdated, and logs a warning when the Excel is newer than the engine supports.

  • Support for buy-and-hold portfolios: a single rebalance date is now valid.

  • Validation preventing any price column (commission_price_column, trade_execution_price_column, mark_to_market_price_column) from being set to the same value as user_column_date.

  • packaging added as an explicit dependency for semantic version comparison.

Changed#

  • __version__ bumped to 0.57.0, __parameters_format_version__ bumped to 0.56.0.

  • CLI module (services/cli.py) aligned stylistically with sibling packages: added -> None return annotations, periods to docstrings, removed dead commented code.

  • dependencies in pyproject.toml sorted alphabetically (case-insensitive).

Fixed#

  • Duplicate log output when ExcelConfigurator was instantiated in a session that already had a root logger configured (logger.propagate = False and handler-deduplication guard added).

0.55.0 (2026-04-01)#

Added#

  • ``load_config_env()`` helper that loads Config/.env into the process environment, eliminating the need to manually set KNPC_API_KEY_KAXANUK=… in the terminal before every run

  • Config/.env template generated automatically by init excel with a placeholder for the license key

  • python-dotenv dependency for .env file loading

  • load_config_env exported at the top-level package namespace (from kaxanuk.backtest_engine import load_config_env)

Changed#

  • Template __main__.py now calls load_config_env() before any license-validated code

  • License error message updated to recommend Config/.env as the primary configuration method

  • README examples updated to include load_config_env() call

0.54.0 (2026-03-31)#

Added#

  • Runtime license validation (phone-home) to protect against unauthorized use

  • license_validator service with device fingerprinting, local cache (24h TTL), and 7-day offline grace period

  • License validation at all entry points: __main__.py, main(), and PyArrowBacktester.run()

  • Custom exception hierarchy: LicenseError, LicenseNotFoundError, LicenseValidationError, LicenseServerError

  • HMAC-signed local cache file (~/.kaxanuk_cache) to prevent tampering

  • In-process validation flag to avoid redundant server calls within the same session

  • httpx dependency for license server communication

Changed#

  • .gitignore updated to exclude .kaxanuk_license and .kaxanuk_cache files

0.52.0 (2026-03-04)#

Added#

  • Batch backtesting capability for running multiple portfolios in a single execution

  • BatchRunner orchestrator with SharedDataPool for efficient market data reuse across portfolios

  • BatchConfigParser for dict/YAML-based batch configuration

  • Directory scanning mode to auto-discover portfolio files

  • Comparative Excel report ranking portfolios by configurable metric

  • Individual Excel reports per portfolio with:

  • Full performance metrics

  • Drawdown analysis

  • Annual returns breakdown

  • Benchmark statistics computation in batch processing

  • Alpha calculation in batch path

Changed#

  • PyArrow Decimal-to-float coercion at numpy math operation boundaries for compatibility

0.51.0 (2026-02-18)#

Added#

  • BacktestSuite class with add_variation() method to define configuration overrides per variation

  • “auto” date derivation from portfolio rebalancing dates

  • Comparative Excel reports with:

  • Summary metrics across all variations

  • Cumulative returns comparison

  • Drawdown comparison charts

Fixed#

  • Alpha metric calculation bug

  • CAGR (Compound Annual Growth Rate) metric calculation bug

0.50.0 (2026-01-16)#

Added#

  • New PyArrow-based backtesting engine (backtest_2) with component-oriented design:

  • Explicit PortfolioStateManager, ExecutionBroker, and ReportingEngine components

  • Pluggable commission and slippage models via interfaces

  • Immutable BacktestReport dataclass as structured result container

  • Clear separation between configuration (inputs) and runtime state

  • Ability to run multiple backtest cases (different parameters) with only one data pipeline

Fixed#

  • Summary card alpha now uses the same calculation as annual returns table, ensuring consistent alpha display across dashboards

0.49.0 (2025-11-25)#

Added#

  • StandardField enum for type-safe field names (VWAP, ADJUSTED_VWAP, ADJUSTED_CLOSE, DATE)

  • Long-short portfolio support with allow_short parameter in PortfolioEntity

  • PortfolioEntity.from_dict() class method for creating portfolios from dictionaries

Changed#

  • Portfolio validation now supports both long-only and long-short strategies

  • README documentation updated

Removed#

  • Unnecessary configuration entity fields

0.48.0 (2025-10-30)#

Added#

  • Annual returns table to Excel report

  • Annual returns analysis to dashboard

  • Alpha metric to annual returns table (both dashboard and Excel report)

Fixed#

  • Performance metrics formatting

  • Dashboard alpha metric format display

0.47.0 (2025-10-15)#

Added#

  • Helper functions module (input_handlers_helpers) for common data processing operations

  • Interactive dropdown menu in portfolio weights evolution chart to filter tickers

  • Comprehensive docstrings to almost all codes

Changed#

  • ExcelPortfolioInputHandler now returns pa.Table instead of pd.DataFrame

  • Dashboard pie chart now displays Top 10 assets alphabetically with “Others” category for remaining positions

  • Benchmark builder now uses ADJ_CLOSE_COLUMN_NAME constant instead of hardcoded strings

  • Excel portfolio validates first column must be ‘Ticker’

0.46.0 (2025-10-06)#

Added#

  • MissingBenchmark exception and benchmark validation before processing

  • Benchmark availability validation (_validate_benchmark_availability())

Changed#

  • Backtest engine optimized (converted class parameters to Python float for better performance)

  • Portfolio transformer now includes all ticker weights (not just >0)

  • Increased decimal precision for financial calculations

Fixed#

  • Portfolio calculation bugs

  • _convert_df_to_python() now properly handles None/NaN values (converts to 0.0)

0.45.0 (2025-10-02)#

Added#

  • Execution price selection option (customizable execution price for backtesting)

  • safe_decimal() function for PyArrow Decimal conversions

  • _convert_df_to_python() method for converting PyArrow scalars to Python values

Changed#

  • Migrated data handling from Pandas to PyArrow

  • Build system changed from pdm-backend to hatchling

Fixed#

  • Input handler and Entities bugs

Removed#

  • Unnecessary project directories and files

0.44.0 (2025-08-27)#

Added#

  • Project templates for easier setup (__main__.py template for CLI init)

  • .gitkeep files for empty directories

Changed#

  • Rebalancing logic improvements

  • CLI interface updates and improvements

  • pdm.lock now excluded from version control

Fixed#

  • CLI bugs

0.43.0 (2025-08-12)#

Added#

  • Benchmark name displayed in plot legends

  • Sortino ratio calculation with robust downside deviation methodology

Changed#

  • Dashboard color scheme updated to company brand colors

  • Interactive pie chart now updates based on selected date

Fixed#

  • Functions for CVaR and VaR calculations with robust historical and parametric Gaussian methods (including Cornish-Fisher modification) were fixed

0.42.0 (2025-07-29)#

Added#

  • Broker interfaces implementation

  • Config factory as alternative to Excel configuration

  • PyArrow-based portfolio entity

  • Custom exceptions for better error handling

  • Mixed date format support

  • New ‘portfolio’ Excel report sheet added

0.41.0 (2025-06-17)#

Added#

  • Portfolio weights evolution plot

  • Custom market data column names support

Changed#

  • Market data builder updated to support custom column names

Fixed#

  • Annualized return calculation

  • CAGR calculation

  • Alpha metric calculation

0.40.1 (2025-06-04)#

Fixed#

  • OS Error on cli init script because of entry script template missing from wheel data

0.40.0 (2025-06-04)#

Changed#

  • First public release, now on PyPI