.. _changelog_v0: V0 Changelog ============ 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