feat(portfolio): add deduct_management_fee for flat annual fee deduction

[Copilot]

Summary

Adds Portfolio.deduct_management_fee to subtract a flat annual management fee from a returns series, accruing pro-rata per calendar day (annual_fee × days_elapsed / 365). Weekends and holidays are charged to the next trading day; the first row always accrues nothing.

Changes

• exceptions.py — new NegativeAnnualFeeError (mirrors NegativeCostBpsError)
• _portfolio_base.py — adds annual_fee: float to _PortfolioMembers TYPE_CHECKING stubs
• portfolio.py — adds annual_fee: float = 0.0 dataclass field; updates cost-model docstring section; updates from_cash_position to accept and forward annual_fee
• _portfolio_constructors.py — from_position and from_risk_position accept and forward annual_fee
• _portfolio_cost.py — implements deduct_management_fee(annual_fee, base):
  • Uses actual calendar-day diffs when a date column is present; falls back to 1 day/period otherwise
  • base defaults to self.returns; accepts any same-schema DataFrame so it composes with cost_adjusted_returns
  • Full input validation (type, finite, non-negative)
• test_costs.py — 16 new tests (zero-fee identity, per-period analytical values, full-year sum, weekend accumulation, composition, validation errors, factory forwarding)

# Set at construction
pf = Portfolio.from_cash_position(prices=prices, cash_position=pos, aum=1e6, annual_fee=0.0085)
net = pf.deduct_management_fee()

# Or compose with trading costs
adj = pf.cost_adjusted_returns(cost_bps=5)
net = pf.deduct_management_fee(annual_fee=0.0085, base=adj)

Testing

• make test passes locally
• make fmt has been run
• New tests added (or explain why not needed)

Checklist

• Commit messages follow the Conventional Commits format
• CHANGELOG.md entry added (or not needed for this change)
• Documentation updated if behaviour changed
• make deptry passes (no unused or missing dependencies)

• Fixes Add management fee deduction utility #898

[Copilot]

Copilot was unable to review this pull request because there is no eligible user to bill. To allow Copilot reviews on bot-authored pull requests, enable direct organization billing in your organization's Copilot settings.

[Copilot]

Copilot was unable to review this pull request because there is no eligible user to bill. To allow Copilot reviews on bot-authored pull requests, enable direct organization billing in your organization's Copilot settings.

[Copilot]

Copilot was unable to review this pull request because there is no eligible user to bill. To allow Copilot reviews on bot-authored pull requests, enable direct organization billing in your organization's Copilot settings.

[Copilot]

Copilot was unable to review this pull request because there is no eligible user to bill. To allow Copilot reviews on bot-authored pull requests, enable direct organization billing in your organization's Copilot settings.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

src/jquantstats/_portfolio_cost.py:213

• deduct_management_fee accepts an arbitrary base frame but doesn't validate it has a 'returns' column and builds the undated days_elapsed via a Python list sized from base.height. This can fail with confusing errors (e.g., ColumnNotFound for missing 'returns') and will produce a length mismatch when base.height == 0 (creating a 1-element Series for a 0-row frame). Adding lightweight validation and generating the undated days_elapsed with pl.arange(...).clip(...) avoids both issues and keeps the operation in Polars.

        if base is None:
            base = self.returns
        if "date" in base.columns and base["date"].dtype.is_temporal():