"Vibe-Trading: Your Personal Trading Agent"
Python ai-agentalgorithmic-tradingbacktestingfintechllmmcpmulti-agentpythonquantitative-financetrading
feat(entities): add the entity and irregular cash-flow spine
Haozhe Wub8276f2abfd5
diff --git a/agent/src/entities/__init__.py b/agent/src/entities/__init__.pynew file mode 100644index 000000000..02d182fa9--- /dev/null+++ b/agent/src/entities/__init__.py@@ -0,0 +1,57 @@+"""Entity and irregular cash-flow spine for holdings that have no daily bar.++This package is a **parallel path** to ``backtest/``, not an extension of it.+The bar path is deliberately narrow: ``backtest.runner._PRICE_PANEL_COLUMNS``+fixes the panel to OHLCV-style fields and+``backtest.loaders.local_loader._normalize_columns`` rejects any file without+``{open, high, low, close}``. That narrowness is a safety property -- if a+``nav`` column were allowed to reach a bar engine it would be priced as a+close, producing a confident wrong answer.++So nothing here feeds a ``BaseEngine``. A ``CashFlowSeries`` is an ordered set+of dated amounts with a currency and a sign convention, consumed by+cash-flow-native analytics rather than by a bar simulator.+"""++from src.entities.cashflow import (+ CashFlow,+ CashFlowSeries,+ CurrencyMismatchError,+ KIND_DIRECTION,+ VALUATION_KINDS,+ normalize_kind,+)+from src.entities.ingest import CashFlowIngestError, load_cashflows+from src.entities.models import (+ Bond,+ Entity,+ EntityType,+ Fund,+ FundStructure,+ Instrument,+ Security,+ SecurityType,+ normalize_currency,+ normalize_date,+)++__all__ = [+ "Bond",+ "CashFlow",+ "CashFlowIngestError",+ "CashFlowSeries",+ "CurrencyMismatchError",+ "Entity",+ "EntityType",+ "Fund",+ "FundStructure",+ "Instrument",+ "KIND_DIRECTION",+ "Security",+ "SecurityType",+ "VALUATION_KINDS",+ "load_cashflows",+ "normalize_currency",+ "normalize_date",+ "normalize_kind",+]diff --git a/agent/src/entities/cashflow.py b/agent/src/entities/cashflow.pynew file mode 100644index 000000000..b8259ebae--- /dev/null+++ b/agent/src/entities/cashflow.py@@ -0,0 +1,418 @@+"""Irregular dated cash flows: the non-bar half of the asset spine.++SIGN CONVENTION (stated once here, enforced in code, never left to callers)+--------------------------------------------------------------------------+Every amount is expressed **from the holder's point of view**:++ amount > 0 cash comes IN to the holder (distribution, coupon, proceeds)+ amount < 0 cash goes OUT from the holder (capital call, purchase, fee)++This is the ordinary IRR/XIRR convention, so a ``CashFlowSeries`` can be fed+straight to a money-weighted return without a caller-side sign flip. Because+callers reliably get this backwards when reading a broker export, the canonical+kinds in ``KIND_DIRECTION`` are *enforced* at construction: a ``capital_call``+with a positive amount is rejected, not quietly accepted.++A movement that is genuinely two-directional (a recallable distribution, an+insurance claim whose direction depends on whether you are the insurer or the+policyholder) must be given its own ``kind``. Kinds absent from+``KIND_DIRECTION`` carry no sign constraint, so the escape hatch is to name the+flow honestly rather than to disable the check.++VALUATIONS ARE NOT CASH+-----------------------+A NAV mark is a valuation, not a settled movement. It is representable here+because terminal NAV is required to compute a fund's IRR or TVPI, but it is+tagged via ``CashFlow.is_valuation`` and excluded from ``CashFlowSeries.total()``+unless explicitly requested. Summing a NAV into realised cash would overstate+distributions, so the default is the conservative one.++CURRENCY IS REQUIRED+--------------------+Every flow carries a currency and a series refuses to mix them. The composite+backtest engine once summed five currencies into a single equity curve; that+was a shipped defect. A series of genuinely translated flows must say so+explicitly via ``pre_translated=True`` *and* name its reporting currency.+"""++from __future__ import annotations++import math+from collections.abc import Iterable, Iterator, Mapping+from dataclasses import dataclass, field+from datetime import date, datetime+from types import MappingProxyType+from typing import Any++from src.entities.models import normalize_currency, normalize_date++__all__ = [+ "CashFlow",+ "CashFlowSeries",+ "CurrencyMismatchError",+ "KIND_DIRECTION",+ "VALUATION_KINDS",+ "normalize_kind",+]++#: Canonical kinds whose direction is definitional, mapped to the required sign+#: of ``amount`` (``-1`` outflow, ``+1`` inflow). A kind absent from this table+#: carries no sign constraint -- see the module docstring.+KIND_DIRECTION: Mapping[str, int] = MappingProxyType(+ {+ # Cash leaving the holder.+ "contribution": -1,+ "capital_call": -1,+ "purchase": -1,+ "subscription": -1,+ "fee": -1,+ "expense": -1,+ # Cash arriving at the holder.+ "distribution": 1,+ "dividend": 1,+ "coupon": 1,+ "interest": 1,+ "principal": 1,+ "redemption": 1,+ "proceeds": 1,+ }+)++#: Kinds that record a mark rather than a settled cash movement. Excluded from+#: ``CashFlowSeries.total()`` by default.+VALUATION_KINDS: frozenset[str] = frozenset({"nav", "residual_value", "valuation"})+++class CurrencyMismatchError(ValueError):+ """Raised when a series would combine amounts in different currencies."""+++def normalize_kind(value: str) -> str:+ """Normalize a cash-flow kind label to its canonical snake_case form.++ Real files spell the same concept as ``"Capital Call"``, ``"capital-call"``,+ or ``"CAPITAL_CALL"``. Normalizing means the sign check in ``KIND_DIRECTION``+ actually bites on those files instead of silently treating each spelling as+ an unconstrained custom kind.++ Args:+ value: Raw kind label from a caller or a file.++ Returns:+ Lower-cased label with spaces and hyphens collapsed to underscores.++ Raises:+ ValueError: If the label is not a string or is blank.+ """+ if not isinstance(value, str):+ raise ValueError(f"kind must be a string, got {type(value).__name__}")+ cleaned = value.strip().lower().replace("-", "_").replace(" ", "_")+ while "__" in cleaned:+ cleaned = cleaned.replace("__", "_")+ if not cleaned:+ raise ValueError("kind is required and cannot be empty")+ return cleaned+++@dataclass(frozen=True)+class CashFlow:+ """A single dated cash amount in one currency.++ Attributes:+ date: Settlement date. ``datetime`` and ISO-8601 strings are accepted+ and normalized to ``datetime.date``.+ amount: Signed amount, positive into the holder. See the module+ docstring for the convention and its enforcement.+ kind: Canonical kind label, e.g. ``"capital_call"`` or ``"coupon"``.+ Normalized via ``normalize_kind``.+ currency: Required currency code, normalized to uppercase.+ metadata: Free-form extra fields, exposed as a read-only mapping so the+ flow stays immutable. Ingestion puts unmapped file columns here+ rather than discarding them.+ """++ date: date+ amount: float+ kind: str+ currency: str+ metadata: Mapping[str, Any] = field(default_factory=dict)++ def __post_init__(self) -> None:+ """Normalize every field and enforce the sign convention.++ Raises:+ ValueError: If the date is unsupported, the amount is not finite,+ the currency or kind is blank, or the amount's sign contradicts+ a canonical kind in ``KIND_DIRECTION``.+ """+ object.__setattr__(self, "date", normalize_date(self.date))+ object.__setattr__(self, "kind", normalize_kind(self.kind))+ object.__setattr__(self, "currency", normalize_currency(self.currency))++ try:+ amount = float(self.amount)+ except (TypeError, ValueError) as exc:+ raise ValueError(+ f"amount must be numeric, got {self.amount!r}"+ ) from exc+ if not math.isfinite(amount):+ raise ValueError(+ f"amount must be a finite number, got {self.amount!r}; a missing "+ "value must be fixed at the source, not carried as NaN"+ )+ object.__setattr__(self, "amount", amount)++ required_sign = KIND_DIRECTION.get(self.kind)+ if required_sign is not None and amount != 0.0:+ if (amount > 0) != (required_sign > 0):+ direction = "positive (cash in)" if required_sign > 0 else "negative (cash out)"+ raise ValueError(+ f"kind={self.kind!r} must have a {direction} amount under the "+ f"holder-perspective sign convention, got {amount!r}. Flip the "+ "sign, or use a distinct kind if this flow is genuinely "+ "two-directional (e.g. 'recallable_distribution')."+ )++ if not isinstance(self.metadata, Mapping):+ raise ValueError(+ f"metadata must be a mapping, got {type(self.metadata).__name__}"+ )+ object.__setattr__(self, "metadata", MappingProxyType(dict(self.metadata)))++ @property+ def is_valuation(self) -> bool:+ """Whether this record is a mark rather than a settled cash movement.++ Returns:+ True when ``kind`` is one of ``VALUATION_KINDS``.+ """+ return self.kind in VALUATION_KINDS+++@dataclass(frozen=True)+class CashFlowSeries:+ """An ordered, immutable collection of ``CashFlow`` in one currency.++ Flows are sorted by date at construction with a stable sort, so several+ flows on the same date keep the order they were supplied in (a call and a+ distribution on the same day usually have a meaningful sequence).++ Attributes:+ flows: The ordered flows, as a tuple.+ currency: Reporting currency of the series. Inferred from the flows+ when they agree; required explicitly when ``pre_translated`` is set.+ ``None`` only for an empty series with no declared currency.+ pre_translated: Set to True to assert that mixed-currency inputs have+ already been converted into ``currency``. This is the *only* way to+ build a series from flows with differing currency codes.+ """++ flows: tuple[CashFlow, ...] = ()+ currency: str | None = None+ pre_translated: bool = False++ def __post_init__(self) -> None:+ """Validate membership and currency coherence, then order by date.++ Raises:+ ValueError: If a member is not a ``CashFlow``, or if+ ``pre_translated`` is set without naming a reporting currency.+ CurrencyMismatchError: If the flows span multiple currencies while+ ``pre_translated`` is False, or contradict a declared currency.+ """+ flows = tuple(self.flows)+ for item in flows:+ if not isinstance(item, CashFlow):+ raise ValueError(+ f"CashFlowSeries members must be CashFlow, got "+ f"{type(item).__name__}"+ )++ declared = (+ normalize_currency(self.currency) if self.currency is not None else None+ )+ present = {flow.currency for flow in flows}++ if self.pre_translated:+ if declared is None:+ raise ValueError(+ "pre_translated=True asserts the flows were already converted, "+ "so the reporting currency must be named explicitly via "+ "currency=..."+ )+ else:+ if len(present) > 1:+ raise CurrencyMismatchError(+ "cash flows span multiple currencies "+ f"({', '.join(sorted(present))}); convert them first and pass "+ "pre_translated=True with the reporting currency, rather than "+ "summing across currencies"+ )+ if declared is None:+ declared = next(iter(present)) if present else None+ elif present and declared not in present:+ raise CurrencyMismatchError(+ f"declared currency {declared!r} does not match the flows' "+ f"currency {next(iter(present))!r}"+ )++ object.__setattr__(self, "currency", declared)+ object.__setattr__(self, "flows", tuple(sorted(flows, key=lambda f: f.date)))++ # ─── Access ───++ def __iter__(self) -> Iterator[CashFlow]:+ """Iterate the flows in date order.++ Returns:+ An iterator over ``CashFlow`` sorted by date.+ """+ return iter(self.flows)++ def __len__(self) -> int:+ """Return the number of flows.++ Returns:+ Count of flows, zero for an empty series.+ """+ return len(self.flows)++ def __getitem__(self, index: int) -> CashFlow:+ """Return the flow at ``index`` in date order.++ Args:+ index: Zero-based position.++ Returns:+ The ``CashFlow`` at that position.++ Raises:+ IndexError: If the position is out of range.+ """+ return self.flows[index]++ @property+ def is_empty(self) -> bool:+ """Whether the series holds no flows.++ Returns:+ True when there are zero flows.+ """+ return not self.flows++ def dates(self) -> tuple[date, ...]:+ """Return every flow date, in order.++ Returns:+ Tuple of dates, possibly with repeats; empty for an empty series.+ """+ return tuple(flow.date for flow in self.flows)++ def amounts(self) -> tuple[float, ...]:+ """Return every signed amount, in date order.++ Returns:+ Tuple of amounts aligned with ``dates()``; empty for an empty series.+ """+ return tuple(flow.amount for flow in self.flows)++ def kinds(self) -> tuple[str, ...]:+ """Return the distinct kinds present, sorted alphabetically.++ Returns:+ Tuple of canonical kind labels; empty for an empty series.+ """+ return tuple(sorted({flow.kind for flow in self.flows}))++ # ─── Derivation ───++ def _rebuild(self, flows: Iterable[CashFlow]) -> CashFlowSeries:+ """Build a derived series that keeps this series' currency contract.++ Args:+ flows: Subset of flows for the new series.++ Returns:+ A new ``CashFlowSeries`` carrying the same currency and+ ``pre_translated`` flag, so a filtered empty series still remembers+ what currency it reports in.+ """+ return CashFlowSeries(+ flows=tuple(flows),+ currency=self.currency,+ pre_translated=self.pre_translated,+ )++ def filter(self, kind: str | Iterable[str] | None = None) -> CashFlowSeries:+ """Select flows by kind.++ Args:+ kind: A single kind label or an iterable of labels. Labels are+ normalized, so ``"Capital Call"`` matches ``"capital_call"``.+ ``None`` returns an equivalent series.++ Returns:+ A new ``CashFlowSeries`` holding only the matching flows.++ Raises:+ ValueError: If a supplied label is blank or not a string.+ """+ if kind is None:+ return self._rebuild(self.flows)+ if isinstance(kind, str):+ wanted = {normalize_kind(kind)}+ else:+ wanted = {normalize_kind(item) for item in kind}+ return self._rebuild(flow for flow in self.flows if flow.kind in wanted)++ def between(+ self,+ start: date | datetime | str | None = None,+ end: date | datetime | str | None = None,+ ) -> CashFlowSeries:+ """Select flows within an inclusive date window.++ Args:+ start: Earliest date to keep, inclusive. ``None`` leaves the window+ open on the left.+ end: Latest date to keep, inclusive. ``None`` leaves it open on the+ right.++ Returns:+ A new ``CashFlowSeries`` holding only flows inside the window.++ Raises:+ ValueError: If a bound is not a supported date value, or if+ ``start`` is later than ``end``.+ """+ lower = normalize_date(start, field_name="start") if start is not None else None+ upper = normalize_date(end, field_name="end") if end is not None else None+ if lower is not None and upper is not None and lower > upper:+ raise ValueError(f"start {lower} is after end {upper}")+ return self._rebuild(+ flow+ for flow in self.flows+ if (lower is None or flow.date >= lower)+ and (upper is None or flow.date <= upper)+ )++ def total(self, *, include_valuations: bool = False) -> float:+ """Sum the signed amounts.++ Valuation marks such as NAV are excluded by default: adding a mark to+ settled cash would overstate what was actually received.++ Args:+ include_valuations: Set True to include ``VALUATION_KINDS`` records,+ as required when computing a fund's IRR against terminal NAV.++ Returns:+ The signed total, ``0.0`` for an empty series.+ """+ return float(+ sum(+ flow.amount+ for flow in self.flows+ if include_valuations or not flow.is_valuation+ )+ )diff --git a/agent/src/entities/ingest.py b/agent/src/entities/ingest.pynew file mode 100644index 000000000..ae3eda7a7--- /dev/null+++ b/agent/src/entities/ingest.py@@ -0,0 +1,474 @@+"""Read irregular dated cash-flow files into a ``CashFlowSeries``.++This is the entry point a user's own file takes into the system. It is a+deliberately separate path from ``backtest/loaders``: that path requires an+OHLC bar and drops every column it does not recognise, which is precisely why a+capital call or a coupon schedule cannot get in through it.++Two rules govern this module:++* **Never return None.** A malformed or mis-mapped file raises+ ``CashFlowIngestError`` naming the file, the row, and the fix. The bar loader+ returns ``None`` for an unrecognised file and the caller sees "no data" with+ no idea why; that failure mode is not repeated here.+* **Never guess.** An ambiguous date format, an ambiguous decimal separator, a+ missing currency, or an unmappable kind is an error, not an inference.+ Guessing day-first vs month-first, or reading ``1.234,50`` as ``1.2345``,+ produces a plausible wrong answer that nothing downstream can detect.++Unmapped columns are preserved into ``CashFlow.metadata`` rather than dropped.+"""++from __future__ import annotations++import csv+import logging+from datetime import date, datetime+from pathlib import Path+from typing import Any, Iterable, Mapping, Sequence++from src.entities.cashflow import CashFlow, CashFlowSeries+from src.entities.models import normalize_date++logger = logging.getLogger(__name__)++__all__ = ["CashFlowIngestError", "load_cashflows"]++#: Canonical field -> the column names accepted for it without an explicit+#: mapping. Matching is case-insensitive and ignores spaces and underscores.+DEFAULT_COLUMN_ALIASES: Mapping[str, tuple[str, ...]] = {+ "date": ("date", "asof", "asofdate", "transactiondate", "valuedate", "paymentdate"),+ "amount": ("amount", "cashflow", "cash", "value", "net", "netamount"),+ "kind": ("kind", "type", "cashflowtype", "transactiontype", "category", "flowtype"),+ "currency": ("currency", "ccy", "curr", "currencycode"),+}++#: Delimiter inferred from the file suffix when the caller does not name one.+_DELIMITER_BY_SUFFIX: Mapping[str, str] = {".csv": ",", ".tsv": "\t", ".txt": ","}++#: Characters removed from a numeric field before parsing: whitespace (including+#: the non-breaking space used by many exports), the Swiss group separator, and+#: currency symbols. Note that ``,`` and ``.`` are deliberately absent -- which+#: one is the decimal separator is resolved per value in ``_parse_amount``,+#: because deleting the wrong one silently turns ``1.234,50`` into ``1.2345``.+_AMOUNT_SYMBOLS = frozenset(" \t\u00a0'$€£¥")++#: Decimal separators a caller may declare explicitly.+_DECIMAL_SEPARATORS = (".", ",")+++class CashFlowIngestError(ValueError):+ """Raised when a cash-flow file cannot be read into a valid series."""+++def _canonical(name: str) -> str:+ """Reduce a column header to its comparison form.++ Args:+ name: Raw header text.++ Returns:+ Lower-cased header with spaces, underscores, and hyphens removed.+ """+ return name.strip().lower().replace(" ", "").replace("_", "").replace("-", "")+++def _resolve_columns(+ header: Sequence[str],+ columns: Mapping[str, str] | None,+ path: Path,+) -> dict[str, str]:+ """Map canonical field names onto this file's actual column headers.++ Args:+ header: Column names as they appear in the file.+ columns: Explicit overrides, canonical field -> file column name.+ path: File path, used only for error messages.++ Returns:+ Mapping of canonical field name to the file's column name, containing+ only fields that were actually found.++ Raises:+ CashFlowIngestError: If an explicit override names a column that the+ file does not contain, or overrides an unknown field.+ """+ resolved: dict[str, str] = {}+ lookup = {_canonical(col): col for col in header}++ if columns:+ for field_name, source_name in columns.items():+ if field_name not in DEFAULT_COLUMN_ALIASES:+ known = ", ".join(sorted(DEFAULT_COLUMN_ALIASES))+ raise CashFlowIngestError(+ f"{path}: unknown column mapping {field_name!r}; "+ f"mappable fields are: {known}"+ )+ if source_name not in header:+ raise CashFlowIngestError(+ f"{path}: mapped column {source_name!r} for field "+ f"{field_name!r} is not in the file. Columns present: "+ f"{', '.join(header)}"+ )+ resolved[field_name] = source_name++ for field_name, aliases in DEFAULT_COLUMN_ALIASES.items():+ if field_name in resolved:+ continue+ for alias in aliases:+ if alias in lookup:+ resolved[field_name] = lookup[alias]+ break++ return resolved+++def _to_plain_number(text: str, decimal_separator: str | None) -> str:+ """Reduce a grouped decimal string to a form ``float`` accepts.++ Args:+ text: Numeric text with symbols already removed, e.g. ``"1,234.50"``.+ decimal_separator: ``"."`` or ``","`` when the caller declared one,+ otherwise ``None`` to infer.++ Returns:+ The same number using ``.`` as the decimal separator and no grouping.++ Raises:+ ValueError: If the value uses a single comma whose role cannot be+ determined -- ``"1,234"`` is 1234 in a US export and 1.234 in a+ European one, and the data cannot say which.+ """+ if decimal_separator is not None:+ grouping = "," if decimal_separator == "." else "."+ return text.replace(grouping, "").replace(decimal_separator, ".")++ has_dot = "." in text+ has_comma = "," in text+ if has_dot and has_comma:+ # The rightmost separator is the decimal one; the other groups digits.+ if text.rindex(".") > text.rindex(","):+ return text.replace(",", "")+ return text.replace(".", "").replace(",", ".")+ if has_comma:+ if text.count(",") > 1:+ return text.replace(",", "") # 1,234,567 cannot be a decimal comma+ raise ValueError(+ f"{text!r} uses a single comma and could be either "+ f"{text.replace(',', '')} (comma groups thousands) or "+ f"{text.replace(',', '.')} (comma is the decimal separator); pass "+ "decimal_separator='.' or decimal_separator=',' to say which"+ )+ return text+++def _parse_amount(+ raw: str,+ path: Path,+ row_number: int,+ decimal_separator: str | None = None,+) -> float:+ """Parse a numeric amount from a file field.++ Handles currency symbols, digit grouping, and the accounting convention+ where parentheses or a trailing minus denote a negative number, e.g.+ ``(1,234.50)``.++ Args:+ raw: Raw cell text.+ path: File path, used only for error messages.+ row_number: 1-based data row number, used only for error messages.+ decimal_separator: Declared decimal separator, or ``None`` to infer.++ Returns:+ The parsed float, negated when the cell was parenthesised or carried a+ trailing minus.++ Raises:+ CashFlowIngestError: If the cell is blank, not numeric, or ambiguously+ grouped.+ """+ text = (raw or "").strip()+ if not text:+ raise CashFlowIngestError(+ f"{path} row {row_number}: amount is blank. A missing amount must be "+ "fixed at the source; it is not treated as zero."+ )++ negative = text.startswith("(") and text.endswith(")")+ if negative:+ text = text[1:-1]+ text = "".join(ch for ch in text if ch not in _AMOUNT_SYMBOLS).strip()+ if text.endswith("-"): # trailing-minus exports+ text = "-" + text[:-1]++ try:+ value = float(_to_plain_number(text, decimal_separator))+ except ValueError as exc:+ raise CashFlowIngestError(+ f"{path} row {row_number}: amount {raw!r} is not usable: {exc}"+ ) from exc+ return -value if negative else value+++def _parse_date(+ raw: str,+ date_format: str | None,+ path: Path,+ row_number: int,+) -> date:+ """Parse a date cell, using an explicit format when one is supplied.++ Args:+ raw: Raw cell text.+ date_format: ``strptime`` format, or ``None`` to require ISO-8601.+ path: File path, used only for error messages.+ row_number: 1-based data row number, used only for error messages.++ Returns:+ The parsed ``datetime.date``.++ Raises:+ CashFlowIngestError: If the cell is blank or does not parse.+ """+ text = (raw or "").strip()+ if not text:+ raise CashFlowIngestError(f"{path} row {row_number}: date is blank")+ if date_format:+ try:+ return datetime.strptime(text, date_format).date()+ except ValueError as exc:+ raise CashFlowIngestError(+ f"{path} row {row_number}: date {raw!r} does not match "+ f"date_format={date_format!r}"+ ) from exc+ try:+ return normalize_date(text)+ except ValueError as exc:+ raise CashFlowIngestError(+ f"{path} row {row_number}: date {raw!r} is not ISO-8601 "+ "(YYYY-MM-DD). Pass date_format=... explicitly; regional formats "+ "are not guessed because day-first and month-first cannot be told "+ "apart from the data."+ ) from exc+++def _read_rows(+ path: Path, delimiter: str | None, encoding: str+) -> tuple[list[str], list[dict[str, str]]]:+ """Read a delimited text file into a header and a list of row mappings.++ Args:+ path: File to read.+ delimiter: Field delimiter, or ``None`` to infer from the suffix.+ encoding: Text encoding.++ Returns:+ Tuple of (header column names, list of row dicts).++ Raises:+ CashFlowIngestError: If the file is missing, unreadable, has an+ unsupported suffix, or has no header row.+ """+ if not path.exists():+ raise CashFlowIngestError(f"cash-flow file not found: {path}")++ if delimiter is None:+ suffix = path.suffix.lower()+ delimiter = _DELIMITER_BY_SUFFIX.get(suffix)+ if delimiter is None:+ supported = ", ".join(sorted(_DELIMITER_BY_SUFFIX))+ raise CashFlowIngestError(+ f"{path}: unsupported file type {suffix!r}; supported suffixes "+ f"are {supported}. Pass delimiter=... to read another format."+ )++ try:+ with open(path, "r", encoding=encoding, newline="") as handle:+ reader = csv.DictReader(handle, delimiter=delimiter)+ header = list(reader.fieldnames or [])+ rows = [dict(row) for row in reader]+ except UnicodeDecodeError as exc:+ raise CashFlowIngestError(+ f"{path}: cannot decode as {encoding!r}; pass encoding=... "+ "(exports from Chinese brokers are often 'gbk')"+ ) from exc+ except OSError as exc:+ raise CashFlowIngestError(f"{path}: cannot read file: {exc}") from exc++ if not header:+ raise CashFlowIngestError(f"{path}: file has no header row")+ return header, rows+++def load_cashflows(+ path: str | Path,+ *,+ columns: Mapping[str, str] | None = None,+ currency: str | None = None,+ default_kind: str | None = None,+ date_format: str | None = None,+ decimal_separator: str | None = None,+ delimiter: str | None = None,+ encoding: str = "utf-8",+ invert_sign: bool = False,+ pre_translated: bool = False,+ metadata_columns: Iterable[str] | None = None,+) -> CashFlowSeries:+ """Load an irregular dated cash-flow file into a ``CashFlowSeries``.++ The file needs a date column and an amount column. Currency and kind may+ come either from a column or from an argument, but must come from+ somewhere: neither is defaulted, because a wrong currency or a bucket+ labelled "unknown" silently corrupts every figure computed downstream.++ Columns that are not mapped to a canonical field are preserved verbatim in+ each ``CashFlow.metadata``.++ Args:+ path: Path to the file. ``.csv``, ``.tsv``, and ``.txt`` are recognised;+ any other suffix requires an explicit ``delimiter``.+ columns: Explicit mapping of canonical field to file column name, e.g.+ ``{"date": "Payment Date", "amount": "Net"}``. Canonical fields are+ ``date``, ``amount``, ``kind``, and ``currency``. Unmapped fields+ fall back to the aliases in ``DEFAULT_COLUMN_ALIASES``.+ currency: Currency for every row. Required when the file has no+ currency column; when both are present this argument names the+ series' reporting currency and the column supplies each row's.+ default_kind: Kind for rows whose kind column is absent or blank.+ date_format: ``strptime`` format for the date column. Omit only when+ the dates are ISO-8601.+ decimal_separator: ``"."`` or ``","``. Needed only for values whose+ grouping is genuinely ambiguous, such as a bare ``"1,234"``.+ delimiter: Field delimiter; inferred from the suffix when omitted.+ encoding: Text encoding of the file.+ invert_sign: Negate every amount after parsing. Use for files that+ report calls as positive, so the holder-perspective convention in+ ``src.entities.cashflow`` is restored at the boundary rather than+ by each caller downstream.+ pre_translated: Assert that a multi-currency file has already been+ converted into ``currency``. Requires ``currency``.+ metadata_columns: Restrict preserved metadata to these columns. By+ default every unmapped column is preserved.++ Returns:+ A ``CashFlowSeries`` ordered by date. An input file with a header but+ no data rows yields an empty series rather than an error.++ Raises:+ CashFlowIngestError: If the file is missing or unreadable, a required+ column is absent, currency or kind cannot be determined, or any row+ fails to parse or violates the sign convention. Never returns None.+ CurrencyMismatchError: If the file's rows span several currencies and+ ``pre_translated`` was not set.+ ValueError: If ``decimal_separator`` is neither ``"."`` nor ``","``.+ """+ if decimal_separator is not None and decimal_separator not in _DECIMAL_SEPARATORS:+ raise ValueError(+ f"decimal_separator must be one of {_DECIMAL_SEPARATORS}, "+ f"got {decimal_separator!r}"+ )++ path = Path(path).expanduser()+ header, rows = _read_rows(path, delimiter, encoding)+ resolved = _resolve_columns(header, columns, path)++ for required in ("date", "amount"):+ if required not in resolved:+ aliases = ", ".join(DEFAULT_COLUMN_ALIASES[required])+ raise CashFlowIngestError(+ f"{path}: required column {required!r} not found. Columns "+ f"present: {', '.join(header)}. Recognised names: {aliases}. "+ f"Pass columns={{{required!r}: '<your column>'}} to map it."+ )++ currency_column = resolved.get("currency")+ if currency_column is None and currency is None:+ raise CashFlowIngestError(+ f"{path}: no currency column found and no currency=... given. "+ "Currency is required; it is never defaulted, because summing "+ "across currencies produces a plausible wrong number."+ )++ kind_column = resolved.get("kind")+ if kind_column is None and default_kind is None:+ raise CashFlowIngestError(+ f"{path}: no kind column found and no default_kind=... given. "+ f"Columns present: {', '.join(header)}."+ )++ mapped_columns = set(resolved.values())+ if metadata_columns is None:+ extra_columns = [col for col in header if col not in mapped_columns]+ else:+ wanted = set(metadata_columns)+ missing = wanted - set(header)+ if missing:+ raise CashFlowIngestError(+ f"{path}: metadata_columns not in file: {', '.join(sorted(missing))}"+ )+ extra_columns = [col for col in header if col in wanted]++ flows: list[CashFlow] = []+ for offset, row in enumerate(rows):+ row_number = offset + 1+ if all(not (value or "").strip() for value in row.values()):+ continue # trailing blank line++ amount = _parse_amount(+ row.get(resolved["amount"], ""), path, row_number, decimal_separator+ )+ if invert_sign:+ amount = -amount++ row_currency = currency+ if currency_column is not None:+ raw_currency = (row.get(currency_column) or "").strip()+ if raw_currency:+ row_currency = raw_currency+ if not row_currency:+ raise CashFlowIngestError(+ f"{path} row {row_number}: currency is blank and no currency=... "+ "fallback was given"+ )++ row_kind = default_kind+ if kind_column is not None:+ raw_kind = (row.get(kind_column) or "").strip()+ if raw_kind:+ row_kind = raw_kind+ if not row_kind:+ raise CashFlowIngestError(+ f"{path} row {row_number}: kind is blank and no default_kind=... "+ "fallback was given"+ )++ metadata: dict[str, Any] = {+ col: row[col] for col in extra_columns if (row.get(col) or "").strip()+ }+ metadata["source_file"] = str(path)+ metadata["source_row"] = row_number++ try:+ flows.append(+ CashFlow(+ date=_parse_date(+ row.get(resolved["date"], ""), date_format, path, row_number+ ),+ amount=amount,+ kind=row_kind,+ currency=row_currency,+ metadata=metadata,+ )+ )+ except CashFlowIngestError:+ raise+ except ValueError as exc:+ raise CashFlowIngestError(f"{path} row {row_number}: {exc}") from exc++ logger.info("loaded %d cash flows from %s", len(flows), path)+ return CashFlowSeries(+ flows=tuple(flows),+ currency=currency,+ pre_translated=pre_translated,+ )diff --git a/agent/src/entities/models.py b/agent/src/entities/models.pynew file mode 100644index 000000000..9c3da9446--- /dev/null+++ b/agent/src/entities/models.py@@ -0,0 +1,396 @@+"""Typed entity and instrument models for the non-bar asset spine.++These models describe *what* is being analysed (a fund, a bond, an issuer),+never *how it traded on a given day*. Anything with a daily OHLCV bar is+already served by ``backtest/loaders`` and its engines; this module exists for+holdings whose economics are a stream of dated cash amounts instead of a price+series (see ``src.entities.cashflow``).++Every model is a frozen dataclass: once constructed, an instance is a fact, not+a mutable scratch buffer. Validation happens once at construction so downstream+code never has to re-check an ``Instrument`` it was handed.++Currency is required on every instrument. A currency-less instrument is the+first step toward summing five currencies into one number, which is exactly the+defect this spine is meant to prevent.+"""++from __future__ import annotations++from dataclasses import dataclass+from datetime import date, datetime+from enum import Enum++__all__ = [+ "Bond",+ "Entity",+ "EntityType",+ "Fund",+ "FundStructure",+ "Instrument",+ "Security",+ "SecurityType",+ "normalize_currency",+ "normalize_date",+]+++class EntityType(str, Enum):+ """Role a legal entity plays relative to an instrument."""++ ISSUER = "issuer"+ MANAGER = "manager"+ SPONSOR = "sponsor"+ COUNTERPARTY = "counterparty"+ SPV = "spv"+ OTHER = "other"+++class SecurityType(str, Enum):+ """Broad class of a listed security."""++ EQUITY = "equity"+ PREFERRED = "preferred"+ ETF = "etf"+ ADR = "adr"+ WARRANT = "warrant"+ OTHER = "other"+++class FundStructure(str, Enum):+ """Whether a fund's capital is drawn down or subscribed at NAV."""++ CLOSED_END = "closed_end"+ OPEN_END = "open_end"+ EVERGREEN = "evergreen"+++def normalize_currency(value: str, *, field_name: str = "currency") -> str:+ """Normalize a currency code to its canonical uppercase form.++ Codes are upper-cased and stripped. Length is deliberately not constrained+ to three characters: this project also handles crypto quote assets such as+ ``USDT``, and rejecting them would push callers into faking a code.++ Args:+ value: Raw currency code, e.g. ``" usd "``.+ field_name: Name used in the error message, for caller context.++ Returns:+ The canonical code, e.g. ``"USD"``.++ Raises:+ ValueError: If the code is empty, not a string, or contains whitespace.+ """+ if not isinstance(value, str):+ raise ValueError(f"{field_name} must be a string, got {type(value).__name__}")+ cleaned = value.strip().upper()+ if not cleaned:+ raise ValueError(f"{field_name} is required and cannot be empty")+ if any(ch.isspace() for ch in cleaned):+ raise ValueError(f"{field_name} cannot contain whitespace, got {value!r}")+ return cleaned+++def normalize_date(value: date | datetime | str, *, field_name: str = "date") -> date:+ """Coerce a supported date input to a plain ``datetime.date``.++ ``datetime`` instances are truncated to their date, because a cash flow+ settles on a day, not at a timestamp; keeping the time component would make+ two flows on the same day compare unequal for no economic reason.++ Strings must be ISO-8601 (``YYYY-MM-DD``, optionally with a time part).+ Ambiguous regional formats such as ``03/04/2024`` are rejected rather than+ guessed, since guessing day-first vs month-first is a silent wrong answer.++ Args:+ value: A ``date``, a ``datetime``, or an ISO-8601 string.+ field_name: Name used in the error message, for caller context.++ Returns:+ The corresponding ``datetime.date``.++ Raises:+ ValueError: If the value is not a supported type or not ISO-8601.+ """+ if isinstance(value, datetime):+ return value.date()+ if isinstance(value, date):+ return value+ if isinstance(value, str):+ text = value.strip()+ if not text:+ raise ValueError(f"{field_name} is required and cannot be empty")+ try:+ return date.fromisoformat(text)+ except ValueError:+ pass+ try:+ return datetime.fromisoformat(text).date()+ except ValueError as exc:+ raise ValueError(+ f"{field_name}={value!r} is not ISO-8601 (YYYY-MM-DD); pass an "+ "explicit date_format instead of relying on inference"+ ) from exc+ raise ValueError(+ f"{field_name} must be a date, datetime, or ISO-8601 string, "+ f"got {type(value).__name__}"+ )+++@dataclass(frozen=True)+class Entity:+ """A legal entity that issues, manages, or faces an instrument.++ Attributes:+ entity_id: Stable identifier, e.g. an LEI, a CIK, or a local key.+ name: Human-readable legal name.+ entity_type: Role the entity plays; see ``EntityType``.+ domicile: Country or jurisdiction code, free-form and optional.+ parent_id: ``entity_id`` of the parent entity, when part of a group.+ """++ entity_id: str+ name: str = ""+ entity_type: EntityType = EntityType.ISSUER+ domicile: str = ""+ parent_id: str | None = None++ def __post_init__(self) -> None:+ """Validate identifiers and coerce ``entity_type`` to its enum member.++ Raises:+ ValueError: If ``entity_id`` is blank or ``entity_type`` is unknown.+ """+ cleaned = self.entity_id.strip() if isinstance(self.entity_id, str) else ""+ if not cleaned:+ raise ValueError("entity_id is required and cannot be empty")+ object.__setattr__(self, "entity_id", cleaned)+ object.__setattr__(self, "name", self.name.strip() if self.name else "")+ try:+ object.__setattr__(self, "entity_type", EntityType(self.entity_type))+ except ValueError as exc:+ valid = ", ".join(member.value for member in EntityType)+ raise ValueError(+ f"unknown entity_type {self.entity_type!r}; expected one of: {valid}"+ ) from exc+ if self.parent_id is not None and self.parent_id == self.entity_id:+ raise ValueError(f"entity {self.entity_id!r} cannot be its own parent")+++@dataclass(frozen=True)+class Instrument:+ """Base class for anything that can be held and analysed.++ Subclasses add asset-class specifics; they may only add fields *with*+ defaults, because the base already declares defaulted fields.++ Attributes:+ instrument_id: Stable identifier, e.g. an ISIN, a ticker, or a local key.+ currency: Required ISO-style currency code of this instrument's cash+ flows. Normalized to uppercase.+ name: Human-readable name.+ issuer: The entity on the hook for the instrument's obligations.+ inception_date: First date the instrument existed, when known.+ """++ instrument_id: str+ currency: str+ name: str = ""+ issuer: Entity | None = None+ inception_date: date | None = None++ def __post_init__(self) -> None:+ """Validate the identifier and normalize currency and inception date.++ Raises:+ ValueError: If ``instrument_id`` is blank, the currency is invalid,+ or ``inception_date`` is not a supported date value.+ """+ cleaned = (+ self.instrument_id.strip() if isinstance(self.instrument_id, str) else ""+ )+ if not cleaned:+ raise ValueError("instrument_id is required and cannot be empty")+ object.__setattr__(self, "instrument_id", cleaned)+ object.__setattr__(self, "currency", normalize_currency(self.currency))+ object.__setattr__(self, "name", self.name.strip() if self.name else "")+ if self.inception_date is not None:+ object.__setattr__(+ self,+ "inception_date",+ normalize_date(self.inception_date, field_name="inception_date"),+ )+++@dataclass(frozen=True)+class Security(Instrument):+ """A listed security identified by a ticker on a venue.++ A ``Security`` here is the *reference* record only. Its price history still+ belongs to the bar-based loader path; this class exists so a corporate+ action or a dividend stream can be attached to a named instrument.++ Attributes:+ symbol: Exchange ticker, e.g. ``"AAPL"`` or ``"600519"``.+ exchange: Venue code, e.g. ``"XNAS"`` or ``"SSE"``.+ security_type: Broad class; see ``SecurityType``.+ """++ symbol: str = ""+ exchange: str = ""+ security_type: SecurityType = SecurityType.EQUITY++ def __post_init__(self) -> None:+ """Validate the base fields and coerce ``security_type``.++ Raises:+ ValueError: If ``security_type`` is not a known member.+ """+ super().__post_init__()+ object.__setattr__(self, "symbol", self.symbol.strip() if self.symbol else "")+ object.__setattr__(+ self, "exchange", self.exchange.strip() if self.exchange else ""+ )+ try:+ object.__setattr__(+ self, "security_type", SecurityType(self.security_type)+ )+ except ValueError as exc:+ valid = ", ".join(member.value for member in SecurityType)+ raise ValueError(+ f"unknown security_type {self.security_type!r}; "+ f"expected one of: {valid}"+ ) from exc+++@dataclass(frozen=True)+class Fund(Instrument):+ """A pooled vehicle whose economics are calls, distributions, and NAV marks.++ This is the archetypal instrument that cannot be expressed as a daily bar:+ a closed-end fund has no price, only an irregular cash-flow stream and a+ periodic valuation.++ Attributes:+ vintage_year: Year the fund began investing, when known.+ structure: Capital structure; see ``FundStructure``.+ strategy: Free-form strategy label, e.g. ``"buyout"``.+ commitment: Total capital committed by the holder, in ``currency``.+ Non-negative; it is a size, not a signed cash flow.+ management_fee_rate: Annual management fee as a decimal fraction+ (``0.02`` means 2%), not a percentage.+ """++ vintage_year: int | None = None+ structure: FundStructure = FundStructure.CLOSED_END+ strategy: str = ""+ commitment: float | None = None+ management_fee_rate: float | None = None++ def __post_init__(self) -> None:+ """Validate the base fields plus fund-specific ranges.++ Raises:+ ValueError: If ``structure`` is unknown, ``commitment`` is+ negative, ``management_fee_rate`` is out of ``[0, 1]``, or+ ``vintage_year`` is implausible.+ """+ super().__post_init__()+ try:+ object.__setattr__(self, "structure", FundStructure(self.structure))+ except ValueError as exc:+ valid = ", ".join(member.value for member in FundStructure)+ raise ValueError(+ f"unknown structure {self.structure!r}; expected one of: {valid}"+ ) from exc+ if self.vintage_year is not None and not 1800 <= int(self.vintage_year) <= 2200:+ raise ValueError(+ f"vintage_year={self.vintage_year!r} is outside the plausible "+ "range 1800-2200"+ )+ if self.commitment is not None:+ if float(self.commitment) < 0:+ raise ValueError(+ f"commitment must be non-negative (it is a size, not a signed "+ f"cash flow), got {self.commitment!r}"+ )+ object.__setattr__(self, "commitment", float(self.commitment))+ if self.management_fee_rate is not None:+ rate = float(self.management_fee_rate)+ if not 0.0 <= rate <= 1.0:+ raise ValueError(+ f"management_fee_rate must be a decimal fraction in [0, 1] "+ f"(0.02 means 2%), got {self.management_fee_rate!r}"+ )+ object.__setattr__(self, "management_fee_rate", rate)+++@dataclass(frozen=True)+class Bond(Instrument):+ """A debt instrument paying scheduled coupons and returning principal.++ Attributes:+ face_value: Redemption amount per unit, in ``currency``. Positive.+ coupon_rate: Annual coupon as a decimal fraction (``0.05`` means 5%),+ not a percentage. Zero marks a zero-coupon bond.+ coupon_frequency: Coupon payments per year. Zero is only valid for a+ zero-coupon bond.+ maturity_date: Redemption date, when known.+ day_count: Day-count convention label, e.g. ``"30/360"`` or+ ``"ACT/365"``. Free-form; consumers decide how to apply it.+ """++ face_value: float | None = None+ coupon_rate: float | None = None+ coupon_frequency: int = 2+ maturity_date: date | None = None+ day_count: str = "30/360"++ def __post_init__(self) -> None:+ """Validate the base fields plus bond-specific ranges and consistency.++ Raises:+ ValueError: If ``face_value`` is non-positive, ``coupon_rate`` is+ negative or expressed as a percentage, the coupon frequency+ contradicts the coupon rate, or maturity precedes inception.+ """+ super().__post_init__()+ if self.face_value is not None:+ face = float(self.face_value)+ if face <= 0:+ raise ValueError(f"face_value must be positive, got {self.face_value!r}")+ object.__setattr__(self, "face_value", face)+ if self.coupon_rate is not None:+ rate = float(self.coupon_rate)+ if rate < 0:+ raise ValueError(f"coupon_rate cannot be negative, got {rate!r}")+ if rate > 1.0:+ raise ValueError(+ f"coupon_rate must be a decimal fraction (0.05 means 5%), "+ f"got {rate!r}; a value above 1.0 is almost certainly a "+ "percentage"+ )+ object.__setattr__(self, "coupon_rate", rate)+ frequency = int(self.coupon_frequency)+ if frequency < 0:+ raise ValueError(+ f"coupon_frequency cannot be negative, got {self.coupon_frequency!r}"+ )+ if self.coupon_rate and frequency == 0:+ raise ValueError(+ f"coupon_frequency=0 marks a zero-coupon bond, but coupon_rate="+ f"{self.coupon_rate!r} is non-zero"+ )+ object.__setattr__(self, "coupon_frequency", frequency)+ if self.maturity_date is not None:+ object.__setattr__(+ self,+ "maturity_date",+ normalize_date(self.maturity_date, field_name="maturity_date"),+ )+ if self.inception_date is not None and self.maturity_date < self.inception_date:+ raise ValueError(+ f"maturity_date {self.maturity_date} precedes inception_date "+ f"{self.inception_date}"+ )diff --git a/agent/src/quantlib/fundmath.py b/agent/src/quantlib/fundmath.pynew file mode 100644index 000000000..a3b1b3b07--- /dev/null+++ b/agent/src/quantlib/fundmath.py@@ -0,0 +1,1298 @@+"""Private-markets fund mathematics on irregular cash flows.++This module is the analytics half of the asset spine: :mod:`src.entities.cashflow`+carries dated, signed, single-currency movements, and everything here turns such+a series into the numbers an LP or a fund controller actually reports.++Three things are deliberate.++**Nothing takes a bare list of floats.** Every public entry point takes a+:class:`~src.entities.cashflow.CashFlowSeries`. A list of floats loses the dates+(so an IRR silently becomes an equal-period IRR), loses the currency (so two+books get summed), and loses the kind (so a NAV mark gets added to realised+cash). All three were real defects; requiring the series makes them unstatable.++**A valuation is not cash.** Terminal NAV belongs in a fund IRR and in TVPI, and+must stay out of DPI. The ``valuations`` policy on :func:`xirr` and the separate+:func:`residual_value` keep that boundary explicit instead of leaving it to the+caller's filtering.++**No garbage roots.** :func:`xirr` refuses a series with no sign change rather+than returning whatever a Newton iteration wandered into, verifies the root it+does return, and exposes :func:`xirr_all` because a fund with recallable+distributions genuinely can have several. See :class:`XIRRError`.++Sign convention is inherited unchanged from the spine: ``amount > 0`` is cash+into the holder, so contributions are negative and distributions positive.+Functions that report a magnitude (``paid_in_capital``, ``distributed_capital``)+return a positive number and say so.+"""++from __future__ import annotations++import datetime as _dt+import math+from collections.abc import Iterable, Sequence+from dataclasses import dataclass++import numpy as np+from scipy.optimize import brentq, newton++from src.entities.cashflow import CashFlow, CashFlowSeries+from src.entities.models import normalize_date++__all__ = [+ "CONTRIBUTION_KINDS",+ "DISTRIBUTION_KINDS",+ "VALUATION_POLICIES",+ "DEFAULT_VALUATION_POLICY",+ "DEFAULT_DAYS_PER_YEAR",+ "DEFAULT_RATE_BOUNDS",+ "DEFAULT_GRID_POINTS",+ "PREFERRED_COMPOUNDING",+ "DEFAULT_PREFERRED_COMPOUNDING",+ "TIER_RETURN_OF_CAPITAL",+ "TIER_PREFERRED_RETURN",+ "TIER_CATCH_UP",+ "TIER_CARRY_SPLIT",+ "XIRRError",+ "NoSignChangeError",+ "XIRRConvergenceError",+ "FundMultiples",+ "WaterfallTier",+ "WaterfallResult",+ "npv",+ "xirr",+ "xirr_all",+ "paid_in_capital",+ "distributed_capital",+ "residual_value",+ "dpi",+ "rvpi",+ "tvpi",+ "moic",+ "fund_multiples",+ "preferred_return_amount",+ "waterfall_split",+ "european_waterfall",+]++#: Kinds treated as capital going into the fund. A parameter everywhere it is+#: used -- a fund that charges management fees outside the commitment should+#: pass ``contribution_kinds=(*CONTRIBUTION_KINDS, "fee")``.+CONTRIBUTION_KINDS: tuple[str, ...] = ("contribution", "capital_call", "subscription")++#: Kinds treated as capital coming back out of the fund.+DISTRIBUTION_KINDS: tuple[str, ...] = (+ "distribution",+ "dividend",+ "redemption",+ "proceeds",+)++#: How :func:`npv` / :func:`xirr` treat valuation marks. ``"terminal"`` keeps+#: only the latest mark (the standard fund-IRR treatment: residual value is+#: assumed liquidated at the measurement date), ``"all"`` keeps every mark+#: (wrong for an IRR unless the series holds exactly one), ``"exclude"`` drops+#: them (a realised-cash-only IRR).+VALUATION_POLICIES: tuple[str, ...] = ("terminal", "all", "exclude")++#: Policy used when the caller does not name one.+DEFAULT_VALUATION_POLICY: str = "terminal"++#: Day basis for converting a date difference into years. 365 is the Excel+#: ``XIRR`` convention and the private-markets norm.+DEFAULT_DAYS_PER_YEAR: float = 365.0++#: Rate window scanned for roots, as ``(low, high)``. The low bound must stay+#: above ``-1``: a rate of ``-100%`` makes every discount factor undefined.+DEFAULT_RATE_BOUNDS: tuple[float, float] = (-0.9999, 1.0e6)++#: Number of samples in the log-spaced bracket scan.+DEFAULT_GRID_POINTS: int = 512++#: Accrual conventions for a preferred return.+PREFERRED_COMPOUNDING: tuple[str, ...] = ("compound", "simple")++#: Preferred-return accrual assumed when the caller does not name one.+DEFAULT_PREFERRED_COMPOUNDING: str = "compound"++#: Waterfall tier labels, in the order they are paid.+TIER_RETURN_OF_CAPITAL: str = "return_of_capital"+TIER_PREFERRED_RETURN: str = "preferred_return"+TIER_CATCH_UP: str = "gp_catch_up"+TIER_CARRY_SPLIT: str = "carry_split"++#: Relative/absolute slack allowed when asserting that a waterfall's tiers sum+#: to the distributable amount. Anything looser would hide a real leak.+_ALLOCATION_TOLERANCE: float = 1e-9++#: NPV residual accepted as "this is a root", scaled by the gross flow size.+_DEFAULT_RESIDUAL_TOLERANCE: float = 1e-10++#: Two roots closer than this in rate space are the same root.+_ROOT_DEDUPE_TOLERANCE: float = 1e-9+++class XIRRError(ValueError):+ """Base class for every reason an irregular-date IRR has no usable answer."""+++class NoSignChangeError(XIRRError):+ """Raised when the flows never change sign, so no finite IRR exists.++ An all-negative or all-positive schedule has no rate at which its present+ value is zero (other than the degenerate limits). Returning a number here+ would be a fabricated result, so this is an error rather than a NaN.+ """+++class XIRRConvergenceError(XIRRError):+ """Raised when the flows do change sign but no root could be verified.++ Both the bracketed scan and the Newton fallback failed to produce a rate+ whose net present value is zero to tolerance.+ """+++# ---------------------------------------------------------------------------+# Series plumbing+# ---------------------------------------------------------------------------+++def _require_series(series: CashFlowSeries, *, name: str = "series") -> CashFlowSeries:+ """Reject anything that is not a ``CashFlowSeries``.++ Args:+ series: Candidate value supplied by the caller.+ name: Parameter name to quote in the error message.++ Returns:+ The same series, unchanged.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``. A bare list of+ floats is refused on purpose -- it carries no dates, no currency and+ no kinds, and every one of those is load-bearing here.+ """+ if not isinstance(series, CashFlowSeries):+ raise TypeError(+ f"{name} must be a CashFlowSeries, got {type(series).__name__}; a bare "+ "sequence of amounts loses the dates, the currency and the flow kinds"+ )+ return series+++def _select_flows(+ series: CashFlowSeries, valuations: str+) -> tuple[CashFlow, ...]:+ """Apply a valuation policy to a series' flows.++ Args:+ series: Source series, already date-ordered by its own constructor.+ valuations: One of :data:`VALUATION_POLICIES`.++ Returns:+ Date-ordered flows after the policy has been applied.++ Raises:+ ValueError: If ``valuations`` is not a recognised policy.+ """+ if valuations not in VALUATION_POLICIES:+ raise ValueError(+ f"valuations={valuations!r} is not one of {VALUATION_POLICIES}"+ )+ flows = tuple(series)+ if valuations == "all":+ return flows+ cash = [flow for flow in flows if not flow.is_valuation]+ if valuations == "exclude":+ return tuple(cash)+ marks = [flow for flow in flows if flow.is_valuation]+ if not marks:+ return tuple(cash)+ # ``flows`` is date-ordered, so the last mark is the terminal one.+ return tuple(sorted([*cash, marks[-1]], key=lambda flow: flow.date))+++def _times_and_amounts(+ flows: Sequence[CashFlow], days_per_year: float+) -> tuple[np.ndarray, np.ndarray]:+ """Convert flows into year offsets from the first date, plus amounts.++ Args:+ flows: Date-ordered flows.+ days_per_year: Day basis, e.g. :data:`DEFAULT_DAYS_PER_YEAR`.++ Returns:+ Tuple ``(times, amounts)`` of float arrays; ``times[0]`` is ``0.0``.++ Raises:+ ValueError: If fewer than two flows are present, if every date is the+ same (no time span, so no rate is identifiable), or if+ ``days_per_year`` is not positive.+ """+ if days_per_year <= 0:+ raise ValueError(f"days_per_year must be positive, got {days_per_year!r}")+ if len(flows) < 2:+ raise ValueError(+ f"an irregular-date IRR needs at least two flows, got {len(flows)}"+ )+ dates = [flow.date for flow in flows]+ start = min(dates)+ if max(dates) == start:+ raise ValueError(+ f"all {len(flows)} flows fall on {start}; a rate of return is not "+ "identifiable without a time span"+ )+ times = np.array([(day - start).days / days_per_year for day in dates], dtype=float)+ amounts = np.array([flow.amount for flow in flows], dtype=float)+ return times, amounts+++def _npv(rate: float, times: np.ndarray, amounts: np.ndarray) -> float:+ """Net present value of dated amounts at one rate.++ Discounting is done in log space (``exp(-t * log1p(r))``) so a large rate+ over a long horizon underflows to zero instead of overflowing a power.++ Args:+ rate: Annual rate as a decimal, strictly greater than ``-1``.+ times: Year offsets from the first flow.+ amounts: Signed amounts aligned with ``times``.++ Returns:+ The net present value, or a non-finite value when the rate is so close+ to ``-1`` that the discount factors overflow. Callers must check.+ """+ if rate <= -1.0:+ return math.nan+ with np.errstate(over="ignore", invalid="ignore", divide="ignore"):+ factors = np.exp(-times * np.log1p(rate))+ total = float(np.sum(amounts * factors))+ return total+++def _npv_derivative(rate: float, times: np.ndarray, amounts: np.ndarray) -> float:+ """First derivative of :func:`_npv` with respect to the rate.++ Args:+ rate: Annual rate as a decimal, strictly greater than ``-1``.+ times: Year offsets from the first flow.+ amounts: Signed amounts aligned with ``times``.++ Returns:+ ``d(NPV)/d(rate)``, or a non-finite value on overflow.+ """+ if rate <= -1.0:+ return math.nan+ with np.errstate(over="ignore", invalid="ignore", divide="ignore"):+ factors = np.exp(-(times + 1.0) * np.log1p(rate))+ total = float(np.sum(-times * amounts * factors))+ return total+++def npv(+ series: CashFlowSeries,+ rate: float,+ *,+ valuations: str = DEFAULT_VALUATION_POLICY,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+) -> float:+ """Net present value of a dated cash-flow series at a given annual rate.++ Discounting is from the series' earliest date, so ``npv(series, 0.0)`` is+ just the sum of the selected amounts.++ Args:+ series: The cash flows. Must be a ``CashFlowSeries``.+ rate: Annual rate as a decimal (``0.08`` is 8%), strictly above ``-1``.+ valuations: One of :data:`VALUATION_POLICIES`; see that constant for+ what each policy does with NAV marks.+ days_per_year: Day basis for the year fraction.++ Returns:+ Present value at the series' first date, in the series' currency.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If the rate is at or below ``-1``, if the policy is+ unknown, if fewer than two flows survive the policy, or if all+ surviving flows share one date.+ """+ _require_series(series)+ if rate <= -1.0:+ raise ValueError(+ f"rate must be greater than -1 (a -100% rate makes every discount "+ f"factor undefined), got {rate!r}"+ )+ flows = _select_flows(series, valuations)+ times, amounts = _times_and_amounts(flows, days_per_year)+ value = _npv(rate, times, amounts)+ if not math.isfinite(value):+ raise ValueError(+ f"net present value overflowed at rate={rate!r}; the rate is too "+ "close to -1 for this horizon"+ )+ return value+++# ---------------------------------------------------------------------------+# XIRR+# ---------------------------------------------------------------------------+++def _scan_roots(+ times: np.ndarray,+ amounts: np.ndarray,+ rate_bounds: tuple[float, float],+ grid_points: int,+ residual_tolerance: float,+) -> list[float]:+ """Find every rate in a window where the NPV crosses or touches zero.++ The window is sampled on a grid that is uniform in ``log(1 + r)``, so the+ same number of points resolves rates near ``-100%`` and rates in the+ thousands of percent. Each sign change is then closed with Brent's method,+ which cannot leave its bracket and therefore cannot report a root that is+ not there.++ Args:+ times: Year offsets from the first flow.+ amounts: Signed amounts aligned with ``times``.+ rate_bounds: ``(low, high)`` rate window; ``low`` must exceed ``-1``.+ grid_points: Number of samples across the window.+ residual_tolerance: Absolute NPV magnitude counted as zero.++ Returns:+ Ascending, de-duplicated roots. Empty when the grid found no crossing.++ Raises:+ ValueError: If the bounds are not ``-1 < low < high``, or if+ ``grid_points`` is below 3.+ """+ low, high = rate_bounds+ if low <= -1.0:+ raise ValueError(f"rate_bounds lower bound must exceed -1, got {low!r}")+ if high <= low:+ raise ValueError(f"rate_bounds must be increasing, got {rate_bounds!r}")+ if grid_points < 3:+ raise ValueError(f"grid_points must be at least 3, got {grid_points!r}")++ rates = np.expm1(np.linspace(math.log1p(low), math.log1p(high), grid_points))+ values = np.array([_npv(float(rate), times, amounts) for rate in rates])++ def objective(rate: float) -> float:+ return _npv(rate, times, amounts)++ roots: list[float] = []+ previous: int | None = None+ for index, value in enumerate(values):+ if not math.isfinite(value):+ continue+ if abs(value) <= residual_tolerance:+ roots.append(float(rates[index]))+ previous = index+ continue+ if (+ previous is not None+ and abs(values[previous]) > residual_tolerance+ and (values[previous] > 0) != (value > 0)+ ):+ roots.append(+ float(brentq(objective, float(rates[previous]), float(rates[index])))+ )+ previous = index++ unique: list[float] = []+ for root in sorted(roots):+ if not unique or abs(root - unique[-1]) > _ROOT_DEDUPE_TOLERANCE:+ unique.append(root)+ return unique+++def xirr_all(+ series: CashFlowSeries,+ *,+ valuations: str = DEFAULT_VALUATION_POLICY,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,+ grid_points: int = DEFAULT_GRID_POINTS,+ residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,+) -> tuple[float, ...]:+ """Every irregular-date IRR of a series inside the scanned rate window.++ A schedule whose signs change more than once (recallable distributions, a+ rescue financing) can have several mathematically valid IRRs. Reporting one+ of them as *the* IRR is a judgement call, so this function hands back all of+ them and :func:`xirr` documents which one it picks.++ Args:+ series: The cash flows.+ valuations: One of :data:`VALUATION_POLICIES`.+ days_per_year: Day basis for the year fraction.+ rate_bounds: ``(low, high)`` rate window to scan; ``low`` must exceed+ ``-1``.+ grid_points: Samples across the window; raise it if a pair of roots sit+ unusually close together.+ residual_tolerance: Relative NPV magnitude counted as zero, scaled by+ the sum of absolute flow amounts.++ Returns:+ Ascending roots. Empty only when the sign check passed but the scan+ found nothing, which :func:`xirr` turns into an error.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ NoSignChangeError: If the surviving amounts are all non-negative or all+ non-positive, or are all zero.+ ValueError: For an unknown policy, a bad rate window, or fewer than two+ dated flows.+ """+ _require_series(series)+ flows = _select_flows(series, valuations)+ times, amounts = _times_and_amounts(flows, days_per_year)++ gross = float(np.sum(np.abs(amounts)))+ if gross == 0.0:+ raise NoSignChangeError(+ "every amount is zero, so no rate of return is defined"+ )+ if not (amounts > 0).any() or not (amounts < 0).any():+ direction = "positive" if (amounts > 0).any() else "negative"+ raise NoSignChangeError(+ f"all {len(amounts)} amounts are {direction}, so the net present "+ "value never crosses zero and no IRR exists. Check the sign "+ "convention: contributions must be negative and distributions "+ "positive. If a terminal NAV is missing, add it as a valuation flow."+ )++ return tuple(+ _scan_roots(+ times,+ amounts,+ rate_bounds,+ grid_points,+ residual_tolerance * gross,+ )+ )+++def xirr(+ series: CashFlowSeries,+ *,+ valuations: str = DEFAULT_VALUATION_POLICY,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ guess: float = 0.1,+ rate_bounds: tuple[float, float] = DEFAULT_RATE_BOUNDS,+ grid_points: int = DEFAULT_GRID_POINTS,+ residual_tolerance: float = _DEFAULT_RESIDUAL_TOLERANCE,+) -> float:+ """Money-weighted return of an irregularly dated cash-flow series.++ Solves ``sum(amount_i / (1 + r) ** t_i) == 0`` where ``t_i`` is the year+ offset of flow ``i`` from the earliest flow.++ Method, and its fallback. The primary solver is a bracketed one: the rate+ window is sampled on a log-spaced grid, and each sign change is closed with+ Brent's method, which is confined to its bracket and so cannot invent a+ root. Only if that scan finds nothing -- which can happen when two roots sit+ inside one grid cell -- does a Newton iteration from ``guess`` run as a+ fallback, and its answer is accepted only after the net present value there+ is checked against ``residual_tolerance``. An unverifiable answer raises+ :class:`XIRRConvergenceError` rather than being returned.++ When several roots exist the smallest is returned, because the alternatives+ are usually artefacts of a sign pattern rather than economics. Call+ :func:`xirr_all` to see them all before trusting the number.++ Args:+ series: The cash flows. Terminal NAV should be present as a valuation+ flow; under the default policy it is included and intermediate+ marks are dropped.+ valuations: One of :data:`VALUATION_POLICIES`.+ days_per_year: Day basis for the year fraction; 365 matches Excel's+ ``XIRR``.+ guess: Starting rate for the Newton fallback only. It has no effect on+ the bracketed path, so a bad guess cannot move the answer.+ rate_bounds: ``(low, high)`` rate window to scan.+ grid_points: Samples across the window.+ residual_tolerance: Relative NPV magnitude counted as zero, scaled by+ the sum of absolute flow amounts.++ Returns:+ The annual rate as a decimal (``0.184`` is 18.4%).++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ NoSignChangeError: If the flows never change sign, so no IRR exists.+ XIRRConvergenceError: If the flows do change sign but no root could be+ found and verified inside ``rate_bounds``.+ ValueError: For an unknown policy, a bad rate window, fewer than two+ dated flows, or flows that all share one date.+ """+ roots = xirr_all(+ series,+ valuations=valuations,+ days_per_year=days_per_year,+ rate_bounds=rate_bounds,+ grid_points=grid_points,+ residual_tolerance=residual_tolerance,+ )+ if roots:+ return roots[0]++ # Documented fallback: the scan is finite, so two roots inside one grid cell+ # leave it empty. Newton can still find one -- but only a verified one is+ # allowed out.+ flows = _select_flows(series, valuations)+ times, amounts = _times_and_amounts(flows, days_per_year)+ gross = float(np.sum(np.abs(amounts)))+ tolerance = residual_tolerance * gross+ low, high = rate_bounds+ try:+ candidate = float(+ newton(+ lambda rate: _npv(rate, times, amounts),+ guess,+ fprime=lambda rate: _npv_derivative(rate, times, amounts),+ )+ )+ except (RuntimeError, OverflowError, ValueError, FloatingPointError) as exc:+ raise XIRRConvergenceError(+ f"no IRR found in ({low}, {high}] by bracketed scan, and the Newton "+ f"fallback from guess={guess!r} failed: {exc}"+ ) from exc++ residual = _npv(candidate, times, amounts)+ if (+ not math.isfinite(candidate)+ or not math.isfinite(residual)+ or candidate <= low+ or candidate > high+ or abs(residual) > tolerance+ ):+ raise XIRRConvergenceError(+ f"no IRR found in ({low}, {high}] by bracketed scan; the Newton "+ f"fallback returned {candidate!r} with a net present value of "+ f"{residual!r}, which is not a root to tolerance {tolerance!r}"+ )+ return candidate+++# ---------------------------------------------------------------------------+# Fund multiples+# ---------------------------------------------------------------------------+++def paid_in_capital(+ series: CashFlowSeries,+ *,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+) -> float:+ """Total capital drawn into the fund, as a positive magnitude.++ Args:+ series: The cash flows.+ contribution_kinds: Kind labels counted as capital in. Defaults to+ :data:`CONTRIBUTION_KINDS`; add ``"fee"`` if the fund's management+ fees are charged outside the commitment and you want them in the+ denominator of the multiples.++ Returns:+ Positive paid-in capital; ``0.0`` when no contributions are present.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If the matched flows net to an inflow, which means their+ signs contradict the holder-perspective convention.+ """+ _require_series(series)+ total = -series.filter(kind=contribution_kinds).total(include_valuations=True)+ if total < 0.0:+ raise ValueError(+ f"contributions net to an inflow of {-total!r}; under the "+ "holder-perspective sign convention capital going into a fund is "+ "negative. Check the contribution_kinds you passed."+ )+ return total+++def distributed_capital(+ series: CashFlowSeries,+ *,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> float:+ """Total capital returned by the fund, as a positive magnitude.++ Args:+ series: The cash flows.+ distribution_kinds: Kind labels counted as capital out. Defaults to+ :data:`DISTRIBUTION_KINDS`.++ Returns:+ Positive distributed capital; ``0.0`` when no distributions are present.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If the matched flows net to an outflow.+ """+ _require_series(series)+ total = series.filter(kind=distribution_kinds).total(include_valuations=True)+ if total < 0.0:+ raise ValueError(+ f"distributions net to an outflow of {-total!r}; under the "+ "holder-perspective sign convention capital coming out of a fund is "+ "positive. Check the distribution_kinds you passed."+ )+ return total+++def residual_value(series: CashFlowSeries) -> float:+ """Unrealised NAV of the fund at its most recent mark.++ Only the latest valuation record counts. Earlier marks are stale by+ definition, and summing them would report a fund's NAV several times over.++ Args:+ series: The cash flows, including any valuation records (``nav``,+ ``residual_value``, ``valuation``).++ Returns:+ The latest mark's amount, or ``0.0`` when the series holds no mark --+ which is the right answer for a fully liquidated fund.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If the latest mark is negative. A negative NAV is possible+ in a levered vehicle but is never what a mis-signed file means, so+ it must be stated as a custom kind rather than inferred here.+ """+ _require_series(series)+ marks = [flow for flow in series if flow.is_valuation]+ if not marks:+ return 0.0+ value = marks[-1].amount+ if value < 0.0:+ raise ValueError(+ f"latest valuation on {marks[-1].date} is {value!r}; a residual "+ "value must be non-negative. If the vehicle really carries negative "+ "equity, record it under a custom kind and compute the multiple "+ "explicitly."+ )+ return value+++def _require_paid_in(paid_in: float) -> float:+ """Reject a zero or negative denominator for a capital multiple.++ Args:+ paid_in: Paid-in capital as a positive magnitude.++ Returns:+ The same value.++ Raises:+ ValueError: If it is not strictly positive -- a multiple of nothing is+ undefined, and returning ``inf`` or ``0`` would both be wrong.+ """+ if paid_in <= 0.0:+ raise ValueError(+ f"paid-in capital is {paid_in!r}; a capital multiple is undefined "+ "with no capital drawn. Confirm the contribution kinds match the file."+ )+ return paid_in+++def dpi(+ series: CashFlowSeries,+ *,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> float:+ """Distributions to paid-in: realised cash returned per unit drawn.++ Args:+ series: The cash flows.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ ``distributed / paid_in``. ``1.0`` is the point where the fund has+ returned the cash it drew.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If no capital was drawn, or if a sign convention is violated.+ """+ paid_in = _require_paid_in(+ paid_in_capital(series, contribution_kinds=contribution_kinds)+ )+ return (+ distributed_capital(series, distribution_kinds=distribution_kinds) / paid_in+ )+++def rvpi(+ series: CashFlowSeries,+ *,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+) -> float:+ """Residual value to paid-in: unrealised NAV per unit drawn.++ Args:+ series: The cash flows, including the latest valuation mark.+ contribution_kinds: Kind labels counted as capital in.++ Returns:+ ``residual_value / paid_in``; ``0.0`` for a fully liquidated fund.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If no capital was drawn, or the latest mark is negative.+ """+ paid_in = _require_paid_in(+ paid_in_capital(series, contribution_kinds=contribution_kinds)+ )+ return residual_value(series) / paid_in+++def tvpi(+ series: CashFlowSeries,+ *,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> float:+ """Total value to paid-in: realised plus unrealised value per unit drawn.++ By construction this is ``dpi + rvpi``; the identity is asserted in the+ tests so the three cannot drift apart.++ Args:+ series: The cash flows.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ ``(distributed + residual_value) / paid_in``.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If no capital was drawn, or a sign convention is violated.+ """+ paid_in = _require_paid_in(+ paid_in_capital(series, contribution_kinds=contribution_kinds)+ )+ distributed = distributed_capital(+ series, distribution_kinds=distribution_kinds+ )+ return (distributed + residual_value(series)) / paid_in+++def moic(+ series: CashFlowSeries,+ *,+ invested_capital: float | None = None,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> float:+ """Multiple on invested capital: total value over the capital put to work.++ At fund level with paid-in as the denominator this equals :func:`tvpi`. The+ two diverge only when the denominator differs -- a deal-level MOIC usually+ excludes fees and undeployed capital -- so that denominator is an explicit+ argument rather than a hidden convention.++ Args:+ series: The cash flows.+ invested_capital: Denominator to use, as a positive magnitude. ``None``+ uses paid-in capital, making the result identical to TVPI.+ contribution_kinds: Kind labels counted as capital in, used only when+ ``invested_capital`` is ``None``.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ ``(distributed + residual_value) / invested_capital``.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If the denominator is not strictly positive, or a sign+ convention is violated.+ """+ if invested_capital is None:+ denominator = paid_in_capital(series, contribution_kinds=contribution_kinds)+ else:+ denominator = float(invested_capital)+ _require_paid_in(denominator)+ distributed = distributed_capital(+ series, distribution_kinds=distribution_kinds+ )+ return (distributed + residual_value(series)) / denominator+++@dataclass(frozen=True)+class FundMultiples:+ """The standard LP reporting multiples, computed from one series.++ Attributes:+ paid_in: Capital drawn, positive magnitude.+ distributed: Capital returned, positive magnitude.+ residual_value: Latest NAV mark, ``0.0`` when fully liquidated.+ dpi: ``distributed / paid_in``.+ rvpi: ``residual_value / paid_in``.+ tvpi: ``dpi + rvpi``.+ moic: Total value over the invested-capital denominator, equal to+ ``tvpi`` when that denominator is paid-in capital.+ invested_capital: The denominator actually used for ``moic``.+ """++ paid_in: float+ distributed: float+ residual_value: float+ dpi: float+ rvpi: float+ tvpi: float+ moic: float+ invested_capital: float+++def fund_multiples(+ series: CashFlowSeries,+ *,+ invested_capital: float | None = None,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> FundMultiples:+ """Compute DPI, RVPI, TVPI and MOIC in one pass over a series.++ Args:+ series: The cash flows.+ invested_capital: Denominator for MOIC; ``None`` uses paid-in capital.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ A :class:`FundMultiples` whose ``tvpi`` is exactly ``dpi + rvpi``.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If no capital was drawn, if the MOIC denominator is not+ positive, or if a sign convention is violated.+ """+ paid_in = _require_paid_in(+ paid_in_capital(series, contribution_kinds=contribution_kinds)+ )+ distributed = distributed_capital(+ series, distribution_kinds=distribution_kinds+ )+ residual = residual_value(series)+ denominator = paid_in if invested_capital is None else float(invested_capital)+ _require_paid_in(denominator)++ distributed_to_paid_in = distributed / paid_in+ residual_to_paid_in = residual / paid_in+ return FundMultiples(+ paid_in=paid_in,+ distributed=distributed,+ residual_value=residual,+ dpi=distributed_to_paid_in,+ rvpi=residual_to_paid_in,+ # Written as the sum, not recomputed, so the identity holds bit-for-bit.+ tvpi=distributed_to_paid_in + residual_to_paid_in,+ moic=(distributed + residual) / denominator,+ invested_capital=denominator,+ )+++# ---------------------------------------------------------------------------+# European (whole-of-fund) waterfall+# ---------------------------------------------------------------------------+++def preferred_return_amount(+ series: CashFlowSeries,+ *,+ rate: float,+ as_of: _dt.date | _dt.datetime | str | None = None,+ compounding: str = DEFAULT_PREFERRED_COMPOUNDING,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+) -> float:+ """Preferred return owed to LPs, accrued per contribution from its own date.++ Accruing each draw separately matters: a fund that called half its capital+ three years after the first close owes materially less hurdle than one that+ called everything on day one, and a single fund-level ``years`` figure+ cannot express that.++ Args:+ series: The cash flows.+ rate: Annual preferred rate as a decimal (``0.08`` is an 8% hurdle).+ Must be non-negative.+ as_of: Measurement date. ``None`` uses the series' latest flow date.+ compounding: One of :data:`PREFERRED_COMPOUNDING`. ``"compound"``+ accrues ``(1 + rate) ** years - 1``; ``"simple"`` accrues+ ``rate * years``.+ days_per_year: Day basis for the year fraction.+ contribution_kinds: Kind labels counted as capital in.++ Returns:+ The preferred return owed, as a positive magnitude excluding the return+ of capital itself. ``0.0`` when nothing has been drawn.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: If the rate is negative, the compounding convention is+ unknown, ``as_of`` precedes a contribution, or ``as_of`` is omitted+ for an empty series.+ """+ _require_series(series)+ if rate < 0.0:+ raise ValueError(f"preferred rate must be non-negative, got {rate!r}")+ if compounding not in PREFERRED_COMPOUNDING:+ raise ValueError(+ f"compounding={compounding!r} is not one of {PREFERRED_COMPOUNDING}"+ )+ if days_per_year <= 0:+ raise ValueError(f"days_per_year must be positive, got {days_per_year!r}")++ contributions = tuple(series.filter(kind=contribution_kinds))+ if not contributions:+ return 0.0++ if as_of is None:+ if series.is_empty:+ raise ValueError("as_of is required for an empty series")+ measurement = max(series.dates())+ else:+ measurement = normalize_date(as_of, field_name="as_of")++ total = 0.0+ for flow in contributions:+ years = (measurement - flow.date).days / days_per_year+ if years < 0.0:+ raise ValueError(+ f"contribution on {flow.date} is after as_of={measurement}; a "+ "preferred return cannot accrue backwards"+ )+ principal = -flow.amount+ if compounding == "compound":+ total += principal * ((1.0 + rate) ** years - 1.0)+ else:+ total += principal * rate * years+ return total+++@dataclass(frozen=True)+class WaterfallTier:+ """One tier of a distribution waterfall and how it split.++ Attributes:+ name: Tier label, one of the ``TIER_*`` constants.+ amount: Dollars that flowed through this tier.+ lp_amount: Portion allocated to the limited partners.+ gp_amount: Portion allocated to the general partner.+ """++ name: str+ amount: float+ lp_amount: float+ gp_amount: float++ def __post_init__(self) -> None:+ """Check that the tier's two shares account for the whole tier.++ Raises:+ ValueError: If ``lp_amount + gp_amount`` differs from ``amount``, or+ if any figure is negative. A waterfall that does not conserve+ cash is a bug, never a rounding artefact worth tolerating.+ """+ for label, value in (+ ("amount", self.amount),+ ("lp_amount", self.lp_amount),+ ("gp_amount", self.gp_amount),+ ):+ if value < -_ALLOCATION_TOLERANCE:+ raise ValueError(+ f"tier {self.name!r} has a negative {label} of {value!r}"+ )+ if not math.isclose(+ self.lp_amount + self.gp_amount,+ self.amount,+ rel_tol=_ALLOCATION_TOLERANCE,+ abs_tol=_ALLOCATION_TOLERANCE,+ ):+ raise ValueError(+ f"tier {self.name!r} does not conserve cash: lp {self.lp_amount!r} "+ f"+ gp {self.gp_amount!r} != {self.amount!r}"+ )+++@dataclass(frozen=True)+class WaterfallResult:+ """Outcome of a European whole-of-fund distribution waterfall.++ Attributes:+ distributable: Cash entering the waterfall.+ contributed_capital: LP capital that must be returned first.+ preferred_amount: Preferred return owed before the GP earns anything.+ tiers: The tiers in payment order.+ lp_total: Everything allocated to the limited partners.+ gp_total: Everything allocated to the general partner.+ unreturned_capital: Contributed capital still outstanding, positive when+ the distributable amount did not cover the return of capital.+ unpaid_preferred: Preferred return still owed, positive when the+ distributable amount did not clear the hurdle.+ """++ distributable: float+ contributed_capital: float+ preferred_amount: float+ tiers: tuple[WaterfallTier, ...]+ lp_total: float+ gp_total: float+ unreturned_capital: float+ unpaid_preferred: float++ def __post_init__(self) -> None:+ """Check that the tiers reconcile to the distributable amount.++ Raises:+ ValueError: If the tier amounts do not sum to ``distributable``, or+ if the per-side totals do not match the tier splits.+ """+ checks = (+ ("distributable", sum(tier.amount for tier in self.tiers), self.distributable),+ ("lp_total", sum(tier.lp_amount for tier in self.tiers), self.lp_total),+ ("gp_total", sum(tier.gp_amount for tier in self.tiers), self.gp_total),+ ("lp+gp", self.lp_total + self.gp_total, self.distributable),+ )+ for label, computed, expected in checks:+ if not math.isclose(+ computed,+ expected,+ rel_tol=_ALLOCATION_TOLERANCE,+ abs_tol=_ALLOCATION_TOLERANCE,+ ):+ raise ValueError(+ f"waterfall does not reconcile on {label}: tiers give "+ f"{computed!r}, expected {expected!r}"+ )++ def tier_amount(self, name: str) -> float:+ """Dollars that flowed through a named tier.++ Args:+ name: One of the ``TIER_*`` constants.++ Returns:+ The tier's ``amount``, or ``0.0`` if that tier is absent.+ """+ for tier in self.tiers:+ if tier.name == name:+ return tier.amount+ return 0.0++ @property+ def gp_profit_share(self) -> float:+ """Fraction of distributed profit that the GP received.++ Profit is everything distributed beyond the return of capital, so this+ is the realised carry percentage. It reaches the nominal carry rate only+ once the catch-up has completed.++ Returns:+ GP total over distributed profit, or ``0.0`` when no profit was+ distributed.+ """+ profit = self.distributable - self.tier_amount(TIER_RETURN_OF_CAPITAL)+ if profit <= 0.0:+ return 0.0+ return self.gp_total / profit+++def waterfall_split(+ distributable: float,+ contributed_capital: float,+ preferred_amount: float,+ *,+ carry_rate: float,+ catch_up_rate: float = 1.0,+) -> WaterfallResult:+ """Split a distributable amount through the four European waterfall tiers.++ The tiers, paid strictly in order and only from what remains:++ 1. **Return of capital** -- 100% to LPs until ``contributed_capital`` is back.+ 2. **Preferred return** -- 100% to LPs until ``preferred_amount`` is paid.+ 3. **GP catch-up** -- ``catch_up_rate`` to the GP, the rest to LPs, until the+ GP holds ``carry_rate`` of all profit distributed so far. Solving+ ``catch_up_rate * C == carry_rate * (preferred_paid + C)`` gives the tier+ size ``C = carry_rate * preferred_paid / (catch_up_rate - carry_rate)``.+ With a 100% catch-up and 20% carry that is ``0.25 * preferred_paid``, and+ the GP then holds exactly 20% of the ``1.25 * preferred_paid`` of profit+ distributed.+ 4. **Carry split** -- the remainder splits ``carry_rate`` to the GP.++ Every rate is a parameter; nothing about 8% / 20% / 100% is baked in.++ Args:+ distributable: Cash to distribute, non-negative.+ contributed_capital: LP capital to return first, non-negative.+ preferred_amount: Preferred return owed, non-negative. See+ :func:`preferred_return_amount` to derive it from a series.+ carry_rate: GP share of profit above the hurdle, in ``[0, 1)``.+ catch_up_rate: GP share of each catch-up dollar, in ``[0, 1]``. Pass+ ``0.0`` for a fund with no catch-up tier; any other value must+ exceed ``carry_rate``, or the tier could never complete.++ Returns:+ A :class:`WaterfallResult` whose tiers sum exactly to ``distributable``.++ Raises:+ ValueError: If any amount is negative, if ``carry_rate`` is outside+ ``[0, 1)``, if ``catch_up_rate`` is outside ``[0, 1]``, or if a+ non-zero ``catch_up_rate`` does not exceed ``carry_rate``.+ """+ for label, value in (+ ("distributable", distributable),+ ("contributed_capital", contributed_capital),+ ("preferred_amount", preferred_amount),+ ):+ if value < 0.0:+ raise ValueError(f"{label} must be non-negative, got {value!r}")+ if not 0.0 <= carry_rate < 1.0:+ raise ValueError(f"carry_rate must be in [0, 1), got {carry_rate!r}")+ if not 0.0 <= catch_up_rate <= 1.0:+ raise ValueError(f"catch_up_rate must be in [0, 1], got {catch_up_rate!r}")+ if catch_up_rate > 0.0 and catch_up_rate <= carry_rate:+ raise ValueError(+ f"catch_up_rate={catch_up_rate!r} must exceed carry_rate="+ f"{carry_rate!r}, otherwise the catch-up tier can never complete. "+ "Pass catch_up_rate=0.0 for a fund with no catch-up."+ )++ remaining = float(distributable)++ return_of_capital = min(remaining, float(contributed_capital))+ remaining -= return_of_capital++ preferred_paid = min(remaining, float(preferred_amount))+ remaining -= preferred_paid++ if catch_up_rate > 0.0 and carry_rate > 0.0:+ catch_up_target = carry_rate * preferred_paid / (catch_up_rate - carry_rate)+ else:+ catch_up_target = 0.0+ catch_up = min(remaining, catch_up_target)+ remaining -= catch_up++ residual = remaining+ gp_residual = carry_rate * residual++ tiers = (+ WaterfallTier(+ name=TIER_RETURN_OF_CAPITAL,+ amount=return_of_capital,+ lp_amount=return_of_capital,+ gp_amount=0.0,+ ),+ WaterfallTier(+ name=TIER_PREFERRED_RETURN,+ amount=preferred_paid,+ lp_amount=preferred_paid,+ gp_amount=0.0,+ ),+ WaterfallTier(+ name=TIER_CATCH_UP,+ amount=catch_up,+ lp_amount=catch_up * (1.0 - catch_up_rate),+ gp_amount=catch_up * catch_up_rate,+ ),+ WaterfallTier(+ name=TIER_CARRY_SPLIT,+ amount=residual,+ lp_amount=residual - gp_residual,+ gp_amount=gp_residual,+ ),+ )+ return WaterfallResult(+ distributable=float(distributable),+ contributed_capital=float(contributed_capital),+ preferred_amount=float(preferred_amount),+ tiers=tiers,+ lp_total=sum(tier.lp_amount for tier in tiers),+ gp_total=sum(tier.gp_amount for tier in tiers),+ unreturned_capital=float(contributed_capital) - return_of_capital,+ unpaid_preferred=float(preferred_amount) - preferred_paid,+ )+++def european_waterfall(+ series: CashFlowSeries,+ *,+ preferred_rate: float,+ carry_rate: float,+ catch_up_rate: float = 1.0,+ as_of: _dt.date | _dt.datetime | str | None = None,+ compounding: str = DEFAULT_PREFERRED_COMPOUNDING,+ days_per_year: float = DEFAULT_DAYS_PER_YEAR,+ include_residual: bool = False,+ contribution_kinds: Iterable[str] = CONTRIBUTION_KINDS,+ distribution_kinds: Iterable[str] = DISTRIBUTION_KINDS,+) -> WaterfallResult:+ """Run a European whole-of-fund waterfall over an actual cash-flow series.++ Contributed capital and the distributable amount are read off the series,+ and the preferred return is accrued per contribution by+ :func:`preferred_return_amount`. The split itself is+ :func:`waterfall_split`.++ Args:+ series: The fund's cash flows.+ preferred_rate: Annual hurdle rate as a decimal.+ carry_rate: GP share of profit above the hurdle, in ``[0, 1)``.+ catch_up_rate: GP share of each catch-up dollar; ``0.0`` for no catch-up.+ as_of: Measurement date for the preferred accrual. ``None`` uses the+ series' latest flow date.+ compounding: One of :data:`PREFERRED_COMPOUNDING`.+ days_per_year: Day basis for the preferred accrual.+ include_residual: ``False`` (default) distributes only realised cash,+ which is what a European waterfall actually does. ``True`` adds the+ latest NAV mark for an "if the fund liquidated today" view -- a+ projection, not a settled split.+ contribution_kinds: Kind labels counted as capital in.+ distribution_kinds: Kind labels counted as capital out.++ Returns:+ A :class:`WaterfallResult` whose tiers sum exactly to the distributable+ amount.++ Raises:+ TypeError: If ``series`` is not a ``CashFlowSeries``.+ ValueError: For a negative rate, an unknown compounding convention, a+ carry or catch-up rate outside its allowed range, a contribution+ dated after ``as_of``, or a sign-convention violation.+ """+ _require_series(series)+ contributed = paid_in_capital(series, contribution_kinds=contribution_kinds)+ distributable = distributed_capital(+ series, distribution_kinds=distribution_kinds+ )+ if include_residual:+ distributable += residual_value(series)+ preferred = preferred_return_amount(+ series,+ rate=preferred_rate,+ as_of=as_of,+ compounding=compounding,+ days_per_year=days_per_year,+ contribution_kinds=contribution_kinds,+ )+ return waterfall_split(+ distributable,+ contributed,+ preferred,+ carry_rate=carry_rate,+ catch_up_rate=catch_up_rate,+ )diff --git a/agent/src/quantlib/performance.py b/agent/src/quantlib/performance.pynew file mode 100644index 000000000..72e771ed4--- /dev/null+++ b/agent/src/quantlib/performance.py@@ -0,0 +1,940 @@+"""Portfolio return when the client, not the manager, moves the money.++``backtest/metrics.py`` computes every figure from an equity curve and a single+scalar ``initial_cash``. That is the right model for a backtest, where the only+capital event is the opening deposit. It cannot express a real client account,+where money arrives and leaves on dates the manager did not choose. Feeding such+an account into a scalar-funded metric silently reports the *client's* deposits+as the *manager's* performance.++This module is the parallel path. It takes a valuation series plus an irregular+:class:`~src.entities.cashflow.CashFlowSeries` and reports the two answers that+actually exist, kept deliberately distinct:++``time_weighted_return``+ True daily-valuation TWR. Chain-links the return of each interval between+ valuations, so the size and the date of an external flow cancel out of the+ product entirely. This is the manager-skill number, and it is what GIPS+ composites report.++``modified_dietz_return``+ The classic day-weighted *approximation* to a money-weighted return. It+ needs only an opening value, a closing value, and dated flows -- no interim+ valuations -- which is why it survives in reporting stacks that cannot+ revalue daily. It is NOT a TWR, despite being widely mislabelled as one; it+ weights each flow by the fraction of the period it was invested and is+ therefore sensitive to flow timing.++``money_weighted_return``+ The internal rate of return (XIRR) of the client's own cash: opening value+ out, flows as they fell, closing value back. This is the client-experience+ number, and it moves with how much money was exposed to which stretch of+ the return path.++WHICH FLOWS ARE EXTERNAL+------------------------+Only movements **across the portfolio boundary** are external. A contribution,+capital call, subscription, transfer in, distribution, redemption, withdrawal,+or transfer out changes the capital base without the manager earning or losing+anything, so it must be removed before a return is struck+(:data:`DEFAULT_EXTERNAL_KINDS`).++A dividend, coupon, interest payment, fee, expense, purchase, or sale proceed is+**internal**: it is already inside the valuation series, and netting it out a+second time double-counts it (:data:`DEFAULT_INTERNAL_KINDS`). Valuation marks+(``nav``, ``residual_value``, ``valuation``) are not cash at all and are ignored.++A kind in neither table is an error, not a default. Silently ignoring an+unrecognised kind would understate the flow adjustment and produce a+plausible-looking wrong return; the caller must classify it explicitly through+``external_kinds=`` or ``internal_kinds=``.++SIGN CONVENTION+---------------+``CashFlow.amount`` is holder-perspective: a ``contribution`` is **negative**+because the cash leaves the client's pocket (see ``src.entities.cashflow``).+The portfolio sees the mirror image, so every external flow is negated exactly+once, here, at :func:`external_flows`. The library never asks a caller to flip+a sign, and :func:`money_weighted_return` consumes ``CashFlow.amount`` as-is+because the holder perspective *is* the IRR perspective.++Only the standard library is imported, matching the rest of ``quantlib``: an+optional numerical dependency missing elsewhere cannot break this module.+"""++from __future__ import annotations++import math+from collections.abc import Iterable, Mapping, Sequence+from dataclasses import dataclass+from datetime import date, datetime++from src.entities.cashflow import CashFlow, CashFlowSeries, normalize_kind+from src.entities.models import normalize_date++__all__ = [+ "DAYS_PER_YEAR",+ "DEFAULT_EXTERNAL_KINDS",+ "DEFAULT_INTERNAL_KINDS",+ "FLOW_TIMING_END",+ "FLOW_TIMING_START",+ "ModifiedDietzReturn",+ "MoneyWeightedReturn",+ "SubPeriodReturn",+ "TimeWeightedReturn",+ "UnsolvableRateError",+ "external_flows",+ "modified_dietz_return",+ "money_weighted_return",+ "time_weighted_return",+ "xirr",+]++#: Day basis for annualisation and for the XIRR time axis. 365 actual days is+#: the XIRR convention (and the one Excel's ``XIRR`` uses), not 252 trading+#: days: client cash moves on calendar dates, including weekends.+DAYS_PER_YEAR = 365.0++#: Kinds that move cash across the portfolio boundary. See the module docstring.+DEFAULT_EXTERNAL_KINDS: frozenset[str] = frozenset(+ {+ "contribution",+ "capital_call",+ "subscription",+ "transfer_in",+ "distribution",+ "redemption",+ "withdrawal",+ "transfer_out",+ }+)++#: Kinds that occur *inside* the portfolio and are therefore already reflected+#: in the valuation series. Netting them out again double-counts them.+DEFAULT_INTERNAL_KINDS: frozenset[str] = frozenset(+ {+ "dividend",+ "coupon",+ "interest",+ "principal",+ "fee",+ "expense",+ "purchase",+ "proceeds",+ }+)++#: A flow dated on a valuation date is deemed to settle *after* that valuation+#: is struck, so it belongs to the period that ends there.+FLOW_TIMING_END = "end"++#: A flow dated on a valuation date is deemed to settle *before* the next+#: interval begins, so it belongs to the period that starts there.+FLOW_TIMING_START = "start"++_FLOW_TIMINGS = (FLOW_TIMING_END, FLOW_TIMING_START)++#: Bisection floor for the IRR search. A rate at or below -100% would make the+#: discount base non-positive, so the solver stops just short of it.+_IRR_LOWER_BOUND = -0.999999++#: Largest rate the bracket expansion will reach before giving up.+_IRR_UPPER_LIMIT = 1e9++#: Absolute width of the final IRR bracket.+_IRR_TOLERANCE = 1e-12++#: Hard iteration cap for the bisection, so a pathological input cannot spin.+_IRR_MAX_ITERATIONS = 400+++class UnsolvableRateError(ValueError):+ """Raised when a cash-flow stream admits no single internal rate of return."""+++@dataclass(frozen=True)+class SubPeriodReturn:+ """One interval between two consecutive valuations.++ Attributes:+ start: Date of the opening valuation of the interval.+ end: Date of the closing valuation of the interval.+ start_value: Portfolio value at ``start``.+ end_value: Portfolio value at ``end``.+ external_flow: Net external cash into the portfolio during the+ interval, portfolio-perspective (positive is money arriving).+ period_return: Return of the interval with the external flow removed.+ """++ start: date+ end: date+ start_value: float+ end_value: float+ external_flow: float+ period_return: float+++@dataclass(frozen=True)+class TimeWeightedReturn:+ """Chain-linked true time-weighted return over the whole window.++ Attributes:+ total_return: Compounded return, ``prod(1 + r_i) - 1``.+ sub_periods: Every interval's decomposition, in date order.+ start_date: Date of the first valuation.+ end_date: Date of the last valuation.+ start_value: Value at ``start_date``.+ end_value: Value at ``end_date``.+ net_external_flow: Sum of the external flows, portfolio-perspective.+ flow_timing: Which boundary a flow dated on a valuation date was+ assigned to; see :data:`FLOW_TIMING_END` and+ :data:`FLOW_TIMING_START`.+ annualized_return: Geometrically annualised ``total_return``, or+ ``None`` when the window is shorter than a year. Annualising a+ three-month figure states a full-year result that was never+ observed, so it is withheld rather than extrapolated.+ """++ total_return: float+ sub_periods: tuple[SubPeriodReturn, ...]+ start_date: date+ end_date: date+ start_value: float+ end_value: float+ net_external_flow: float+ flow_timing: str+ annualized_return: float | None+++@dataclass(frozen=True)+class ModifiedDietzReturn:+ """Day-weighted money-weighted approximation over a single period.++ Attributes:+ total_return: ``(V1 - V0 - F) / (V0 + sum(w_i * F_i))``.+ start_date: Opening date of the period.+ end_date: Closing date of the period.+ start_value: Value at ``start_date``.+ end_value: Value at ``end_date``.+ net_external_flow: ``F``, the sum of external flows.+ weighted_external_flow: ``sum(w_i * F_i)``.+ average_capital: The denominator, ``V0 + sum(w_i * F_i)``.+ flow_weights: ``(date, amount, weight)`` per external flow, in date+ order, so a reported figure can be audited line by line.+ annualized_return: Geometrically annualised ``total_return``, or+ ``None`` for a window shorter than a year.+ """++ total_return: float+ start_date: date+ end_date: date+ start_value: float+ end_value: float+ net_external_flow: float+ weighted_external_flow: float+ average_capital: float+ flow_weights: tuple[tuple[date, float, float], ...]+ annualized_return: float | None+++@dataclass(frozen=True)+class MoneyWeightedReturn:+ """Internal rate of return of the client's own cash.++ Attributes:+ annualized_return: The XIRR itself, an annual rate on a+ :data:`DAYS_PER_YEAR` actual-day basis.+ period_return: ``(1 + annualized_return) ** years - 1``, the same rate+ expressed over the observed window rather than per annum.+ start_date: Date of the opening valuation.+ end_date: Date of the closing valuation.+ start_value: Opening value, entered into the IRR as an outflow.+ end_value: Closing value, entered into the IRR as an inflow.+ net_external_flow: Net external cash into the portfolio,+ portfolio-perspective, for reconciliation against the TWR result.+ years: Window length in years on the same actual-day basis.+ iterations: Bisection steps the solver used, exposed so a+ near-degenerate stream is visible rather than silently trusted.+ """++ annualized_return: float+ period_return: float+ start_date: date+ end_date: date+ start_value: float+ end_value: float+ net_external_flow: float+ years: float+ iterations: int+++# ─── Input normalisation ───+++def _normalize_valuations(+ valuations: Mapping[date | datetime | str, float]+ | Sequence[tuple[date | datetime | str, float]],+) -> tuple[tuple[date, float], ...]:+ """Coerce a valuation series to sorted ``(date, value)`` pairs.++ Args:+ valuations: Either a mapping of date to value, or a sequence of+ two-element ``(date, value)`` pairs. Dates go through+ ``src.entities.models.normalize_date``, so ISO-8601 strings and+ ``datetime`` instances are accepted.++ Returns:+ Pairs sorted by date, with at least two entries.++ Raises:+ ValueError: If fewer than two valuations were supplied, a pair is+ malformed, a value is not finite, or a date repeats. A repeated+ date is rejected rather than deduplicated because two different+ marks for one day have no defensible ordering.+ """+ if isinstance(valuations, Mapping):+ raw_items: list[tuple[object, object]] = list(valuations.items())+ else:+ raw_items = []+ for index, item in enumerate(valuations):+ if isinstance(item, (str, bytes)) or not isinstance(item, Sequence):+ raise ValueError(+ f"valuations[{index}] must be a (date, value) pair, got "+ f"{type(item).__name__}"+ )+ pair = tuple(item)+ if len(pair) != 2:+ raise ValueError(+ f"valuations[{index}] must have exactly two elements "+ f"(date, value), got {len(pair)}"+ )+ raw_items.append((pair[0], pair[1]))++ if len(raw_items) < 2:+ raise ValueError(+ "a return needs an opening and a closing valuation; got "+ f"{len(raw_items)}"+ )++ resolved: list[tuple[date, float]] = []+ for raw_date, raw_value in raw_items:+ when = normalize_date(raw_date, field_name="valuation date")+ try:+ value = float(raw_value)+ except (TypeError, ValueError) as exc:+ raise ValueError(+ f"valuation on {when} must be numeric, got {raw_value!r}"+ ) from exc+ if not math.isfinite(value):+ raise ValueError(+ f"valuation on {when} must be finite, got {raw_value!r}; a "+ "missing mark must be fixed at the source, not carried as NaN"+ )+ resolved.append((when, value))++ resolved.sort(key=lambda item: item[0])+ for earlier, later in zip(resolved, resolved[1:], strict=False):+ if earlier[0] == later[0]:+ raise ValueError(+ f"two valuations share the date {earlier[0]}; a single day can "+ "carry only one mark"+ )+ return tuple(resolved)+++def external_flows(+ flows: CashFlowSeries | Iterable[CashFlow] | None,+ *,+ external_kinds: Iterable[str] | None = None,+ internal_kinds: Iterable[str] | None = None,+) -> tuple[tuple[date, float], ...]:+ """Select the boundary-crossing flows and restate them portfolio-side.++ The returned amounts are the **negation** of ``CashFlow.amount``: the input+ is holder-perspective (a contribution is cash leaving the client, hence+ negative), the output is portfolio-perspective (a contribution is cash+ arriving, hence positive). This is the only place in the module where that+ flip happens.++ Args:+ flows: A ``CashFlowSeries``, any iterable of ``CashFlow``, or ``None``+ for a period with no client activity.+ external_kinds: Kinds to treat as boundary-crossing. Defaults to+ :data:`DEFAULT_EXTERNAL_KINDS`. Labels are normalised, so+ ``"Capital Call"`` matches ``"capital_call"``.+ internal_kinds: Kinds to treat as already inside the valuation series.+ Defaults to :data:`DEFAULT_INTERNAL_KINDS`.++ Returns:+ ``(date, amount_into_portfolio)`` pairs in date order. Several flows on+ one date stay as several entries; callers that need one number per date+ aggregate themselves.++ Raises:+ ValueError: If a flow's kind appears in both classifications, or in+ neither. An unclassified kind is refused rather than assumed+ internal, because assuming would understate the flow adjustment and+ return a plausible wrong number.+ """+ if flows is None:+ return ()++ external = (+ DEFAULT_EXTERNAL_KINDS+ if external_kinds is None+ else frozenset(normalize_kind(kind) for kind in external_kinds)+ )+ internal = (+ DEFAULT_INTERNAL_KINDS+ if internal_kinds is None+ else frozenset(normalize_kind(kind) for kind in internal_kinds)+ )+ overlap = external & internal+ if overlap:+ raise ValueError(+ "a kind cannot be both external and internal; overlapping: "+ f"{', '.join(sorted(overlap))}"+ )++ selected: list[tuple[date, float]] = []+ for flow in flows:+ if flow.is_valuation:+ continue+ if flow.kind in external:+ selected.append((flow.date, -flow.amount))+ elif flow.kind not in internal:+ raise ValueError(+ f"cash-flow kind {flow.kind!r} on {flow.date} is classified "+ "neither external nor internal, so it cannot be treated as "+ "either. Pass external_kinds=[...] or internal_kinds=[...] to "+ "say which side of the portfolio boundary it crosses. Known "+ f"external: {', '.join(sorted(external))}. Known internal: "+ f"{', '.join(sorted(internal))}."+ )+ selected.sort(key=lambda item: item[0])+ return tuple(selected)+++def _annualize(total_return: float, days: int) -> float | None:+ """Annualise a holding-period return, or decline to when the window is short.++ Args:+ total_return: Return over the whole window, as a decimal fraction.+ days: Calendar days spanned by the window.++ Returns:+ The annualised return, or ``None`` when ``days`` is below+ :data:`DAYS_PER_YEAR`. A total wipeout annualises to ``-1.0``, matching+ ``backtest/metrics.py``'s handling of a non-positive growth factor+ rather than raising a negative base to a fractional power.+ """+ if days < DAYS_PER_YEAR:+ return None+ growth = 1.0 + total_return+ if growth <= 0.0:+ return -1.0+ try:+ return float(growth ** (DAYS_PER_YEAR / days) - 1.0)+ except OverflowError:+ return None+++# ─── Time-weighted return ───+++def _assign_flows_to_periods(+ dates: Sequence[date],+ flows: Sequence[tuple[date, float]],+ flow_timing: str,+) -> list[float]:+ """Bucket external flows into the intervals between valuations.++ With :data:`FLOW_TIMING_END` interval ``k`` covers ``(d[k-1], d[k]]``, so a+ flow dated on a valuation date belongs to the interval ending there and a+ flow dated on the *first* valuation is already inside the opening value.+ With :data:`FLOW_TIMING_START` interval ``k`` covers ``[d[k-1], d[k])``, so+ a flow dated on a valuation date opens the next interval and a flow on the+ *last* valuation falls outside the window.++ Args:+ dates: Valuation dates in ascending order.+ flows: Portfolio-perspective ``(date, amount)`` pairs.+ flow_timing: One of :data:`FLOW_TIMING_END` / :data:`FLOW_TIMING_START`.++ Returns:+ One net flow per interval, so ``len(dates) - 1`` entries.++ Raises:+ ValueError: If a flow falls outside the valuation window. Dropping it+ silently would move the client's money into the manager's return.+ """+ first, last = dates[0], dates[-1]+ buckets = [0.0] * (len(dates) - 1)+ for when, amount in flows:+ if when < first or when > last:+ raise ValueError(+ f"cash flow on {when} lies outside the valuation window "+ f"{first}..{last}; extend the valuations or trim the flows "+ "rather than dropping the flow"+ )+ if flow_timing == FLOW_TIMING_END:+ if when == first:+ raise ValueError(+ f"cash flow on {when} coincides with the opening valuation "+ f"and flow_timing={FLOW_TIMING_END!r} places it inside the "+ "opening value, where it would be counted twice. Use "+ f"flow_timing={FLOW_TIMING_START!r}, or start the "+ "valuations one period earlier."+ )+ # First interval whose closing date is at or after the flow.+ index = next(k for k in range(1, len(dates)) if dates[k] >= when) - 1+ else:+ if when == last:+ raise ValueError(+ f"cash flow on {when} coincides with the closing valuation "+ f"and flow_timing={FLOW_TIMING_START!r} places it after the "+ "window ends. Use flow_timing="+ f"{FLOW_TIMING_END!r}, or extend the valuations."+ )+ # Last interval whose opening date is at or before the flow.+ index = max(k for k in range(len(dates) - 1) if dates[k] <= when)+ buckets[index] += amount+ return buckets+++def time_weighted_return(+ valuations: Mapping[date | datetime | str, float]+ | Sequence[tuple[date | datetime | str, float]],+ flows: CashFlowSeries | Iterable[CashFlow] | None = None,+ *,+ flow_timing: str = FLOW_TIMING_END,+ external_kinds: Iterable[str] | None = None,+ internal_kinds: Iterable[str] | None = None,+) -> TimeWeightedReturn:+ """Chain-link the true time-weighted return across a valuation series.++ Each interval's return removes that interval's external flow before+ dividing, so the product telescopes to the return a single unit of capital+ would have earned. Neither the size nor the date of a client contribution+ can move it -- that invariance is the entire reason the measure exists, and+ it is what distinguishes this from :func:`modified_dietz_return`.++ For ``flow_timing=FLOW_TIMING_END`` the interval return is+ ``(V_k - F_k) / V_{k-1} - 1``: the flow arrives after the market has moved,+ so it earns nothing that interval. For ``FLOW_TIMING_START`` it is+ ``V_k / (V_{k-1} + F_k) - 1``: the flow is invested for the whole interval.+ Both are exact given the stated timing; picking the wrong one biases every+ interval that carried a flow.++ Only boundary-crossing flows are removed; dividends, coupons, and fees are+ internal and already sit in the valuations. See the module docstring.++ Args:+ valuations: Portfolio value on each valuation date, as a mapping or as+ ``(date, value)`` pairs. At least two are required, and more+ valuations make the answer more exact -- this is *true* TWR, not an+ approximation, only to the resolution the marks provide.+ flows: Client cash flows over the window. ``None`` means none.+ flow_timing: Which side of a valuation date a flow dated on it settles.+ external_kinds: Override for :data:`DEFAULT_EXTERNAL_KINDS`.+ internal_kinds: Override for :data:`DEFAULT_INTERNAL_KINDS`.++ Returns:+ A :class:`TimeWeightedReturn` carrying the compounded figure and every+ interval that produced it.++ Raises:+ ValueError: If fewer than two valuations were given, ``flow_timing`` is+ not a recognised token, a flow falls outside the window or on a+ boundary the timing cannot represent, a flow's kind is+ unclassified, or an interval's invested base is not strictly+ positive. A non-positive base has no honest percentage: an account+ that reached zero did not "return" anything on the way back.+ """+ if flow_timing not in _FLOW_TIMINGS:+ raise ValueError(+ f"flow_timing must be one of {_FLOW_TIMINGS}, got {flow_timing!r}"+ )++ marks = _normalize_valuations(valuations)+ dates = [when for when, _ in marks]+ values = [value for _, value in marks]+ selected = external_flows(+ flows, external_kinds=external_kinds, internal_kinds=internal_kinds+ )+ buckets = _assign_flows_to_periods(dates, selected, flow_timing)++ sub_periods: list[SubPeriodReturn] = []+ growth = 1.0+ for index, flow_amount in enumerate(buckets):+ opening = values[index]+ closing = values[index + 1]+ if flow_timing == FLOW_TIMING_END:+ base = opening+ numerator = closing - flow_amount+ else:+ base = opening + flow_amount+ numerator = closing+ if not base > 0.0:+ raise ValueError(+ f"interval {dates[index]}..{dates[index + 1]} has an invested "+ f"base of {base!r}; a return is undefined on zero or negative "+ "capital, so the window must start after the account was funded"+ )+ period_return = numerator / base - 1.0+ growth *= 1.0 + period_return+ sub_periods.append(+ SubPeriodReturn(+ start=dates[index],+ end=dates[index + 1],+ start_value=opening,+ end_value=closing,+ external_flow=flow_amount,+ period_return=period_return,+ )+ )++ total_return = growth - 1.0+ return TimeWeightedReturn(+ total_return=total_return,+ sub_periods=tuple(sub_periods),+ start_date=dates[0],+ end_date=dates[-1],+ start_value=values[0],+ end_value=values[-1],+ net_external_flow=math.fsum(buckets),+ flow_timing=flow_timing,+ annualized_return=_annualize(total_return, (dates[-1] - dates[0]).days),+ )+++# ─── Modified Dietz ───+++def modified_dietz_return(+ valuations: Mapping[date | datetime | str, float]+ | Sequence[tuple[date | datetime | str, float]],+ flows: CashFlowSeries | Iterable[CashFlow] | None = None,+ *,+ external_kinds: Iterable[str] | None = None,+ internal_kinds: Iterable[str] | None = None,+) -> ModifiedDietzReturn:+ """Compute the day-weighted Modified Dietz return over one period.++ ``R = (V1 - V0 - F) / (V0 + sum(w_i * F_i))`` with+ ``w_i = (CD - D_i) / CD``, where ``CD`` is the calendar length of the period+ and ``D_i`` the days from its start to flow ``i``. A flow on the opening day+ carries weight 1 (invested throughout); one on the closing day carries+ weight 0 (invested for none of it).++ This is a **money-weighted** measure. It approximates the IRR by assuming a+ constant rate of return within the period, and it is sensitive to when the+ client moved money -- the opposite property to+ :func:`time_weighted_return`. It is offered because it needs no interim+ valuations, not because it is a cheaper TWR.++ Only the first and last valuations are used; any interim marks are ignored+ by construction. Pass them to :func:`time_weighted_return` instead.++ Args:+ valuations: Portfolio values; the earliest is ``V0`` and the latest is+ ``V1``. At least two are required.+ flows: Client cash flows over the period. ``None`` means none.+ external_kinds: Override for :data:`DEFAULT_EXTERNAL_KINDS`.+ internal_kinds: Override for :data:`DEFAULT_INTERNAL_KINDS`.++ Returns:+ A :class:`ModifiedDietzReturn` carrying the return and every term of+ its denominator.++ Raises:+ ValueError: If fewer than two valuations were given, the opening and+ closing dates coincide, a flow lies outside the period, a flow's+ kind is unclassified, or the average capital is not strictly+ positive (an account funded to zero average capital has no return).+ """+ marks = _normalize_valuations(valuations)+ start_date, start_value = marks[0]+ end_date, end_value = marks[-1]+ calendar_days = (end_date - start_date).days+ if calendar_days <= 0:+ raise ValueError(+ f"Modified Dietz needs a period of at least one day, got "+ f"{start_date}..{end_date}"+ )++ selected = external_flows(+ flows, external_kinds=external_kinds, internal_kinds=internal_kinds+ )+ weights: list[tuple[date, float, float]] = []+ for when, amount in selected:+ if when < start_date or when > end_date:+ raise ValueError(+ f"cash flow on {when} lies outside the period "+ f"{start_date}..{end_date}; trim the flows or widen the period "+ "rather than dropping the flow"+ )+ weight = (calendar_days - (when - start_date).days) / calendar_days+ weights.append((when, amount, weight))++ net_flow = math.fsum(amount for _, amount, _ in weights)+ weighted_flow = math.fsum(amount * weight for _, amount, weight in weights)+ average_capital = start_value + weighted_flow+ if not average_capital > 0.0:+ raise ValueError(+ f"average capital is {average_capital!r}; Modified Dietz is "+ "undefined on a non-positive invested base"+ )++ total_return = (end_value - start_value - net_flow) / average_capital+ return ModifiedDietzReturn(+ total_return=total_return,+ start_date=start_date,+ end_date=end_date,+ start_value=start_value,+ end_value=end_value,+ net_external_flow=net_flow,+ weighted_external_flow=weighted_flow,+ average_capital=average_capital,+ flow_weights=tuple(weights),+ annualized_return=_annualize(total_return, calendar_days),+ )+++# ─── Money-weighted return ───+++def _npv(rate: float, years: Sequence[float], amounts: Sequence[float]) -> float:+ """Net present value of dated amounts at an annual rate.++ Args:+ rate: Annual discount rate, strictly above -100%.+ years: Time from the first flow, in years, aligned with ``amounts``.+ amounts: Signed amounts.++ Returns:+ The discounted sum. A term whose discount factor overflows to beyond+ the float range contributes ``0.0``, which is its limit, rather than+ raising and aborting the search.+ """+ base = 1.0 + rate+ terms: list[float] = []+ for exponent, amount in zip(years, amounts, strict=True):+ try:+ terms.append(amount / (base**exponent))+ except OverflowError:+ terms.append(0.0)+ return math.fsum(terms)+++def _solve_irr(+ years: Sequence[float], amounts: Sequence[float]+) -> tuple[float, int]:+ """Bisect for the annual rate that zeroes the net present value.++ Bisection is used rather than Newton because it cannot diverge and needs no+ guess. The bracket starts just above -100% -- where the NPV is dominated by+ the latest, largest-exponent amount -- and expands upward until the sign+ flips.++ Args:+ years: Time from the first flow, in years, ascending.+ amounts: Signed amounts aligned with ``years``.++ Returns:+ ``(rate, iterations)``.++ Raises:+ UnsolvableRateError: If the stream never changes sign, or if no rate+ below :data:`_IRR_UPPER_LIMIT` brackets a root. Both mean there is+ no single rate to report, which is a real property of the stream and+ not a solver failure to paper over.+ """+ if not any(amount > 0 for amount in amounts) or not any(+ amount < 0 for amount in amounts+ ):+ raise UnsolvableRateError(+ "an internal rate of return needs at least one inflow and one "+ "outflow; this stream is one-directional"+ )++ low = _IRR_LOWER_BOUND+ npv_low = _npv(low, years, amounts)+ if npv_low == 0.0:+ return low, 0+ high = 1.0+ npv_high = _npv(high, years, amounts)+ iterations = 0+ while npv_low * npv_high > 0.0 and high < _IRR_UPPER_LIMIT:+ high *= 2.0+ npv_high = _npv(high, years, amounts)+ iterations += 1+ if npv_low * npv_high > 0.0:+ raise UnsolvableRateError(+ "no internal rate of return between "+ f"{_IRR_LOWER_BOUND:.6f} and {_IRR_UPPER_LIMIT:.0f} explains this "+ "stream; the net present value never changes sign"+ )++ while iterations < _IRR_MAX_ITERATIONS and (high - low) > _IRR_TOLERANCE:+ middle = 0.5 * (low + high)+ npv_middle = _npv(middle, years, amounts)+ if npv_middle == 0.0:+ return middle, iterations+ if npv_low * npv_middle < 0.0:+ high = middle+ else:+ low, npv_low = middle, npv_middle+ iterations += 1+ return 0.5 * (low + high), iterations+++def xirr(+ dated_amounts: Sequence[tuple[date | datetime | str, float]],+) -> float:+ """Annual internal rate of return of irregularly dated amounts.++ Amounts are holder-perspective, matching ``CashFlow.amount``: money paid out+ is negative, money received is positive. Several amounts on one date are+ summed. Time is measured in actual days over :data:`DAYS_PER_YEAR`.++ A stream with more than one sign change can admit several mathematically+ valid rates. This returns whichever root the bisection isolates inside its+ initial bracket, and does not enumerate the rest: a stream where that+ matters is one whose "the IRR" is not a well-defined quantity, and no+ solver choice repairs that. Check the sign pattern before quoting the+ number.++ Args:+ dated_amounts: ``(date, amount)`` pairs. Order does not matter.++ Returns:+ The annual rate as a decimal fraction, e.g. ``0.087`` for 8.7%.++ Raises:+ ValueError: If fewer than two amounts were given, a date or amount is+ unusable, or every amount falls on one date.+ UnsolvableRateError: If the stream is one-directional or no rate+ brackets a root.+ """+ if len(dated_amounts) < 2:+ raise ValueError(+ f"an IRR needs at least two dated amounts, got {len(dated_amounts)}"+ )++ totals: dict[date, float] = {}+ for raw_date, raw_amount in dated_amounts:+ when = normalize_date(raw_date, field_name="cash-flow date")+ try:+ amount = float(raw_amount)+ except (TypeError, ValueError) as exc:+ raise ValueError(+ f"amount on {when} must be numeric, got {raw_amount!r}"+ ) from exc+ if not math.isfinite(amount):+ raise ValueError(f"amount on {when} must be finite, got {raw_amount!r}")+ totals[when] = totals.get(when, 0.0) + amount++ ordered = sorted(totals.items())+ if len(ordered) < 2:+ raise ValueError(+ f"every amount falls on {ordered[0][0]}; an IRR needs a time span"+ )++ origin = ordered[0][0]+ years = [(when - origin).days / DAYS_PER_YEAR for when, _ in ordered]+ amounts = [amount for _, amount in ordered]+ rate, _ = _solve_irr(years, amounts)+ return rate+++def money_weighted_return(+ valuations: Mapping[date | datetime | str, float]+ | Sequence[tuple[date | datetime | str, float]],+ flows: CashFlowSeries | Iterable[CashFlow] | None = None,+ *,+ external_kinds: Iterable[str] | None = None,+ internal_kinds: Iterable[str] | None = None,+) -> MoneyWeightedReturn:+ """Compute the client's money-weighted return (XIRR) over the window.++ The client's cash stream is the opening value paid in, every external flow+ as it fell, and the closing value taken back out. Because+ ``CashFlow.amount`` is already holder-perspective, the flows enter the IRR+ unchanged; only the two valuations need signs attached, and they get the+ signs a purchase and a sale would carry.++ This answers "what did the client's money earn", so unlike+ :func:`time_weighted_return` it is *supposed* to move when a large+ contribution lands just before a drawdown. Report both, never one as a+ proxy for the other.++ Interim valuations are ignored: an IRR is determined by cash, and marking+ the account midway does not change what the client paid or received.++ Args:+ valuations: Portfolio values; the earliest opens the stream and the+ latest closes it. At least two are required.+ flows: Client cash flows over the window. ``None`` means none, in which+ case the IRR is just the annualised growth of the opening value.+ external_kinds: Override for :data:`DEFAULT_EXTERNAL_KINDS`.+ internal_kinds: Override for :data:`DEFAULT_INTERNAL_KINDS`.++ Returns:+ A :class:`MoneyWeightedReturn` with both the annualised rate and the+ same rate restated over the observed window.++ Raises:+ ValueError: If fewer than two valuations were given, the window has no+ length, a flow lies outside it, or a flow's kind is unclassified.+ UnsolvableRateError: If the resulting stream admits no single rate --+ for instance a closing value of zero with no distributions, where+ every amount points the same way.+ """+ marks = _normalize_valuations(valuations)+ start_date, start_value = marks[0]+ end_date, end_value = marks[-1]+ if (end_date - start_date).days <= 0:+ raise ValueError(+ f"a money-weighted return needs a window of at least one day, got "+ f"{start_date}..{end_date}"+ )++ selected = external_flows(+ flows, external_kinds=external_kinds, internal_kinds=internal_kinds+ )+ for when, _ in selected:+ if when < start_date or when > end_date:+ raise ValueError(+ f"cash flow on {when} lies outside the window "+ f"{start_date}..{end_date}; trim the flows or widen the window "+ "rather than dropping the flow"+ )++ # Portfolio-perspective flows are negated back to the client's perspective:+ # cash arriving in the portfolio is cash the client paid out.+ stream: list[tuple[date, float]] = [(start_date, -start_value)]+ stream.extend((when, -amount) for when, amount in selected)+ stream.append((end_date, end_value))++ totals: dict[date, float] = {}+ for when, amount in stream:+ totals[when] = totals.get(when, 0.0) + amount+ ordered = sorted(totals.items())+ origin = ordered[0][0]+ years = [(when - origin).days / DAYS_PER_YEAR for when, _ in ordered]+ amounts = [amount for _, amount in ordered]+ rate, iterations = _solve_irr(years, amounts)++ window_years = (end_date - start_date).days / DAYS_PER_YEAR+ return MoneyWeightedReturn(+ annualized_return=rate,+ period_return=(1.0 + rate) ** window_years - 1.0,+ start_date=start_date,+ end_date=end_date,+ start_value=start_value,+ end_value=end_value,+ net_external_flow=math.fsum(amount for _, amount in selected),+ years=window_years,+ iterations=iterations,+ )diff --git a/agent/src/tools/cashflow_analytics_tool.py b/agent/src/tools/cashflow_analytics_tool.pynew file mode 100644index 000000000..edba480a9--- /dev/null+++ b/agent/src/tools/cashflow_analytics_tool.py@@ -0,0 +1,488 @@+"""Agent tool for client-cash-flow-aware portfolio performance.++Read-only. It reports the time-weighted, Modified Dietz, and money-weighted+returns of an account whose owner moved money in and out mid-period, which the+backtest metric path cannot express because it is funded by a single scalar.+No order path exists here and none may be added: this is a research surface.+"""++from __future__ import annotations++import json+import math+from datetime import date+from typing import Any++from src.agent.tools import BaseTool+from src.entities.cashflow import CashFlow, CashFlowSeries+from src.entities.ingest import load_cashflows+from src.quantlib.performance import (+ DEFAULT_EXTERNAL_KINDS,+ DEFAULT_INTERNAL_KINDS,+ FLOW_TIMING_END,+ FLOW_TIMING_START,+ UnsolvableRateError,+ modified_dietz_return,+ money_weighted_return,+ time_weighted_return,+)++#: Upper bound on inline records, so one tool call cannot blow the context+#: window. Larger histories belong in a file and go through ``flows_path``.+_MAX_VALUATIONS = 4000+_MAX_INLINE_FLOWS = 4000++#: Decimal places used for every number in the envelope. Six is enough to carry+#: a return to a hundredth of a basis point without emitting float noise.+_ROUNDING = 6+++class CashFlowPerformanceTool(BaseTool):+ """Report TWR, Modified Dietz, and money-weighted return for a client account."""++ name = "cashflow_performance"+ description = (+ "Measure the return of an account that received client contributions "+ "or paid out withdrawals mid-period. Takes a dated valuation series "+ "plus irregular cash flows (inline records or a CSV path) and returns "+ "the true time-weighted return (manager skill, immune to flow timing), "+ "the Modified Dietz day-weighted approximation, and the money-weighted "+ "XIRR (client experience). External flows are contributions, capital "+ "calls, subscriptions, transfers, distributions, redemptions and "+ "withdrawals; dividends, coupons, interest and fees are internal and "+ "already inside the valuations. Research only; places no orders."+ )+ repeatable = True+ is_readonly = True+ parameters = {+ "type": "object",+ "properties": {+ "valuations": {+ "type": "array",+ "minItems": 2,+ "maxItems": _MAX_VALUATIONS,+ "description": (+ "Portfolio value on each valuation date, earliest first. "+ "Two entries give a single-period answer; add interim "+ "marks to make the time-weighted return exact."+ ),+ "items": {+ "type": "object",+ "properties": {+ "date": {+ "type": "string",+ "description": "ISO-8601 date, e.g. 2024-06-30.",+ },+ "value": {"type": "number"},+ },+ "required": ["date", "value"],+ },+ },+ "flows": {+ "type": "array",+ "maxItems": _MAX_INLINE_FLOWS,+ "description": (+ "Inline cash flows. Amounts are from the client's point of "+ "view: a contribution is NEGATIVE (cash leaves the client) "+ "and a distribution is POSITIVE. Mutually exclusive with "+ "flows_path."+ ),+ "items": {+ "type": "object",+ "properties": {+ "date": {"type": "string"},+ "amount": {"type": "number"},+ "kind": {+ "type": "string",+ "description": (+ "e.g. contribution, withdrawal, distribution, "+ "capital_call, dividend."+ ),+ },+ "currency": {+ "type": "string",+ "description": "Overrides the top-level currency.",+ },+ },+ "required": ["date", "amount", "kind"],+ },+ },+ "flows_path": {+ "type": "string",+ "description": (+ "Path to a delimited cash-flow file (.csv/.tsv/.txt). "+ "Mutually exclusive with flows."+ ),+ },+ "currency": {+ "type": "string",+ "description": (+ "Reporting currency. Required for inline flows that do not "+ "carry their own, and for a file with no currency column."+ ),+ },+ "flows_default_kind": {+ "type": "string",+ "description": "Kind for file rows whose kind column is absent or blank.",+ },+ "flows_date_format": {+ "type": "string",+ "description": "strptime format for the file's date column, if not ISO-8601.",+ },+ "flows_columns": {+ "type": "object",+ "description": (+ "Map canonical field to file column name, e.g. "+ '{"date": "Payment Date", "amount": "Net"}.'+ ),+ "additionalProperties": {"type": "string"},+ },+ "flows_invert_sign": {+ "type": "boolean",+ "default": False,+ "description": (+ "Negate every file amount, for exports that report "+ "contributions as positive."+ ),+ },+ "flow_timing": {+ "type": "string",+ "enum": [FLOW_TIMING_END, FLOW_TIMING_START],+ "default": FLOW_TIMING_END,+ "description": (+ "Whether a flow dated on a valuation date settles after "+ "that valuation ('end') or before the next interval "+ "('start'). Affects the time-weighted return only."+ ),+ },+ "external_kinds": {+ "type": "array",+ "items": {"type": "string"},+ "description": "Override the default set of boundary-crossing kinds.",+ },+ "internal_kinds": {+ "type": "array",+ "items": {"type": "string"},+ "description": "Override the default set of inside-the-portfolio kinds.",+ },+ },+ "required": ["valuations"],+ }++ def execute(self, **kwargs: Any) -> str:+ """Compute the three returns and package them in one envelope.++ Args:+ **kwargs: Inputs described by :attr:`parameters`.++ Returns:+ A JSON envelope with ``status``, ``inputs``, ``summary``,+ ``sub_periods``, per-measure detail, ``notes`` and ``limitations``.+ Invalid input returns a JSON error envelope; it never raises and+ never returns ``None``.+ """+ notes: list[str] = []+ try:+ valuations = _coerce_valuations(kwargs.get("valuations"))+ series = _resolve_flows(kwargs)+ flow_timing = _coerce_flow_timing(kwargs.get("flow_timing"))+ external_kinds = _coerce_kinds(kwargs.get("external_kinds"), "external_kinds")+ internal_kinds = _coerce_kinds(kwargs.get("internal_kinds"), "internal_kinds")++ twr = time_weighted_return(+ valuations,+ series,+ flow_timing=flow_timing,+ external_kinds=external_kinds,+ internal_kinds=internal_kinds,+ )+ dietz = modified_dietz_return(+ valuations,+ series,+ external_kinds=external_kinds,+ internal_kinds=internal_kinds,+ )+ except (KeyError, OSError, TypeError, ValueError) as exc:+ return _error(str(exc))++ try:+ mwr = money_weighted_return(+ valuations,+ series,+ external_kinds=external_kinds,+ internal_kinds=internal_kinds,+ )+ except UnsolvableRateError as exc:+ # A one-directional stream has no IRR. That is a property of the+ # account, not a failure, so the other two measures still ship.+ mwr = None+ notes.append(f"money-weighted return not reported: {exc}")++ payload = {+ "status": "ok",+ "tool": self.name,+ "inputs": {+ "valuation_count": len(valuations),+ "flow_count": len(series) if series is not None else 0,+ "flow_source": (+ "flows_path"+ if kwargs.get("flows_path")+ else "inline" if kwargs.get("flows") else "none"+ ),+ "flow_timing": flow_timing,+ "currency": series.currency if series is not None else kwargs.get("currency"),+ "external_kinds": sorted(external_kinds or DEFAULT_EXTERNAL_KINDS),+ "internal_kinds": sorted(internal_kinds or DEFAULT_INTERNAL_KINDS),+ },+ "summary": {+ "start_date": twr.start_date.isoformat(),+ "end_date": twr.end_date.isoformat(),+ "start_value": _rounded(twr.start_value),+ "end_value": _rounded(twr.end_value),+ "net_external_flow": _rounded(twr.net_external_flow),+ "time_weighted_return": _rounded(twr.total_return),+ "time_weighted_annualized": _rounded_or_none(twr.annualized_return),+ "modified_dietz_return": _rounded(dietz.total_return),+ "modified_dietz_annualized": _rounded_or_none(dietz.annualized_return),+ "money_weighted_return_annualized": (+ None if mwr is None else _rounded(mwr.annualized_return)+ ),+ "money_weighted_return_period": (+ None if mwr is None else _rounded(mwr.period_return)+ ),+ },+ "sub_periods": [+ {+ "start": period.start.isoformat(),+ "end": period.end.isoformat(),+ "start_value": _rounded(period.start_value),+ "end_value": _rounded(period.end_value),+ "external_flow": _rounded(period.external_flow),+ "return": _rounded(period.period_return),+ }+ for period in twr.sub_periods+ ],+ "modified_dietz": {+ "net_external_flow": _rounded(dietz.net_external_flow),+ "weighted_external_flow": _rounded(dietz.weighted_external_flow),+ "average_capital": _rounded(dietz.average_capital),+ "flow_weights": [+ {+ "date": when.isoformat(),+ "amount": _rounded(amount),+ "weight": _rounded(weight),+ }+ for when, amount, weight in dietz.flow_weights+ ],+ },+ "money_weighted": (+ None+ if mwr is None+ else {+ "annualized_return": _rounded(mwr.annualized_return),+ "period_return": _rounded(mwr.period_return),+ "years": _rounded(mwr.years),+ "solver_iterations": mwr.iterations,+ }+ ),+ "notes": notes,+ "limitations": [+ "Flow amounts are holder-perspective: a contribution is negative.",+ "Only contributions, withdrawals and transfers are treated as "+ "external; dividends, coupons and fees are assumed already "+ "inside the valuation series.",+ "Modified Dietz is a money-weighted approximation, not a "+ "cheaper time-weighted return.",+ "Returns are gross of any fee not already reflected in the "+ "valuations, and carry no tax or currency translation.",+ ],+ }+ return json.dumps(payload, ensure_ascii=False, allow_nan=False)+++def _coerce_valuations(raw: Any) -> list[tuple[date, float]]:+ """Parse the raw valuation array into ``(date, value)`` pairs.++ Args:+ raw: Value supplied for the ``valuations`` parameter.++ Returns:+ Pairs in the order supplied; the library sorts and validates them.++ Raises:+ ValueError: If the array is missing, wrongly shaped, over the size cap,+ or an entry lacks a usable date or value.+ """+ if not isinstance(raw, list) or len(raw) < 2:+ raise ValueError("valuations must be an array of at least two {date, value} objects")+ if len(raw) > _MAX_VALUATIONS:+ raise ValueError(f"valuations may contain at most {_MAX_VALUATIONS} entries")++ pairs: list[tuple[date, float]] = []+ for index, item in enumerate(raw):+ if not isinstance(item, dict):+ raise ValueError(f"valuations[{index}] must be an object with date and value")+ if "date" not in item or "value" not in item:+ raise ValueError(f"valuations[{index}] needs both 'date' and 'value'")+ try:+ value = float(item["value"])+ except (TypeError, ValueError) as exc:+ raise ValueError(f"valuations[{index}].value must be numeric") from exc+ if not math.isfinite(value):+ raise ValueError(f"valuations[{index}].value must be finite")+ pairs.append((item["date"], value))+ return pairs+++def _resolve_flows(kwargs: dict[str, Any]) -> CashFlowSeries | None:+ """Build the cash-flow series from inline records or from a file.++ Args:+ kwargs: The tool's raw inputs.++ Returns:+ A ``CashFlowSeries``, or ``None`` when no flows were supplied.++ Raises:+ ValueError: If both sources were given, an inline record is malformed,+ or a currency is missing. File problems surface as+ ``CashFlowIngestError``, which is a ``ValueError``.+ """+ inline = kwargs.get("flows")+ path = kwargs.get("flows_path")+ if inline and path:+ raise ValueError("pass either flows or flows_path, not both")+ currency = kwargs.get("currency")++ if path:+ columns = kwargs.get("flows_columns")+ if columns is not None and not isinstance(columns, dict):+ raise ValueError("flows_columns must be an object mapping field to column name")+ return load_cashflows(+ str(path),+ columns=columns,+ currency=currency,+ default_kind=kwargs.get("flows_default_kind"),+ date_format=kwargs.get("flows_date_format"),+ invert_sign=bool(kwargs.get("flows_invert_sign", False)),+ )++ if not inline:+ return None+ if not isinstance(inline, list):+ raise ValueError("flows must be an array of {date, amount, kind} objects")+ if len(inline) > _MAX_INLINE_FLOWS:+ raise ValueError(f"flows may contain at most {_MAX_INLINE_FLOWS} entries")++ records: list[CashFlow] = []+ for index, item in enumerate(inline):+ if not isinstance(item, dict):+ raise ValueError(f"flows[{index}] must be an object")+ row_currency = item.get("currency") or currency+ if not row_currency:+ raise ValueError(+ f"flows[{index}] has no currency and no top-level currency was "+ "given; currency is never defaulted"+ )+ try:+ records.append(+ CashFlow(+ date=item["date"],+ amount=item["amount"],+ kind=item["kind"],+ currency=row_currency,+ )+ )+ except KeyError as exc:+ raise ValueError(f"flows[{index}] is missing {exc.args[0]!r}") from exc+ except ValueError as exc:+ raise ValueError(f"flows[{index}]: {exc}") from exc+ return CashFlowSeries(tuple(records))+++def _coerce_flow_timing(raw: Any) -> str:+ """Validate the flow-timing token.++ Args:+ raw: Value supplied for ``flow_timing``; ``None`` selects the default.++ Returns:+ Either :data:`~src.quantlib.performance.FLOW_TIMING_END` or+ :data:`~src.quantlib.performance.FLOW_TIMING_START`.++ Raises:+ ValueError: If the token is not one of the two recognised values.+ """+ if raw is None or raw == "":+ return FLOW_TIMING_END+ token = str(raw).strip().lower()+ if token not in (FLOW_TIMING_END, FLOW_TIMING_START):+ raise ValueError(+ f"flow_timing must be {FLOW_TIMING_END!r} or {FLOW_TIMING_START!r}, "+ f"got {raw!r}"+ )+ return token+++def _coerce_kinds(raw: Any, field_name: str) -> list[str] | None:+ """Validate an optional kind-classification override.++ Args:+ raw: Value supplied for ``external_kinds`` or ``internal_kinds``.+ field_name: Name used in the error message.++ Returns:+ The list of labels, or ``None`` to keep the module default.++ Raises:+ ValueError: If the value is not an array of non-empty strings.+ """+ if raw is None:+ return None+ if not isinstance(raw, list) or not raw:+ raise ValueError(f"{field_name} must be a non-empty array of kind labels")+ labels: list[str] = []+ for item in raw:+ if not isinstance(item, str) or not item.strip():+ raise ValueError(f"{field_name} entries must be non-empty strings")+ labels.append(item)+ return labels+++def _rounded(value: float) -> float:+ """Round a finite scalar for stable, compact JSON.++ Args:+ value: Number to round.++ Returns:+ The value rounded to :data:`_ROUNDING` decimal places.+ """+ return round(float(value), _ROUNDING)+++def _rounded_or_none(value: float | None) -> float | None:+ """Round a scalar that may be deliberately absent.++ Args:+ value: Number to round, or ``None``.++ Returns:+ The rounded value, or ``None`` when the caller had nothing to report.+ """+ return None if value is None else _rounded(value)+++def _error(message: str) -> str:+ """Build the tool's stable error envelope.++ Args:+ message: Operator-facing explanation.++ Returns:+ A JSON string with ``status`` set to ``"error"``.+ """+ return json.dumps(+ {"status": "error", "tool": CashFlowPerformanceTool.name, "error": message},+ ensure_ascii=False,+ )diff --git a/agent/tests/quantlib/test_fundmath.py b/agent/tests/quantlib/test_fundmath.pynew file mode 100644index 000000000..7c15510d7--- /dev/null+++ b/agent/tests/quantlib/test_fundmath.py@@ -0,0 +1,726 @@+"""Tests for src.quantlib.fundmath.++Two rules the assertions here follow.++*Roots are checked against a construction, not against the solver.* The XIRR+tests build a schedule whose net present value at a chosen rate is zero by+arithmetic, then ask the solver to find that rate back. The annual-spacing test+goes further and cross-checks against a polynomial root found by ``np.roots``,+which shares no code with the module under test.++*The waterfall example is worked by hand in the docstring of its test.* Every+tier figure is derived on paper first, so a wrong implementation cannot make the+test agree with itself.+"""++import datetime as dt++import numpy as np+import pytest++from src.entities.cashflow import CashFlow, CashFlowSeries+from src.quantlib.fundmath import (+ CONTRIBUTION_KINDS,+ TIER_CARRY_SPLIT,+ TIER_CATCH_UP,+ TIER_PREFERRED_RETURN,+ TIER_RETURN_OF_CAPITAL,+ FundMultiples,+ NoSignChangeError,+ WaterfallResult,+ WaterfallTier,+ XIRRConvergenceError,+ XIRRError,+ distributed_capital,+ dpi,+ european_waterfall,+ fund_multiples,+ moic,+ npv,+ paid_in_capital,+ preferred_return_amount,+ residual_value,+ rvpi,+ tvpi,+ waterfall_split,+ xirr,+ xirr_all,+)++DAYS_PER_YEAR = 365.0+++# --------------------------------------------------------------------------+# helpers+# --------------------------------------------------------------------------+++def make_series(rows, *, currency: str = "USD") -> CashFlowSeries:+ """Build a series from ``(date, amount, kind)`` triples."""+ return CashFlowSeries(+ tuple(CashFlow(date=d, amount=a, kind=k, currency=currency) for d, a, k in rows)+ )+++def constructed_schedule(rate: float) -> CashFlowSeries:+ """A schedule whose XIRR is exactly ``rate``, by construction.++ Four irregularly dated inflows are chosen freely; the single opening outflow+ is then set to minus their present value at ``rate``, which forces the net+ present value at ``rate`` to zero.+ """+ start = dt.date(2019, 3, 15)+ inflows = [+ (dt.date(2019, 11, 2), 120.0),+ (dt.date(2021, 6, 30), 450.0),+ (dt.date(2022, 2, 14), 300.0),+ (dt.date(2024, 9, 1), 800.0),+ ]+ present_value = sum(+ amount / (1.0 + rate) ** ((day - start).days / DAYS_PER_YEAR)+ for day, amount in inflows+ )+ rows = [(start, -present_value, "purchase")]+ rows.extend((day, amount, "proceeds") for day, amount in inflows)+ return make_series(rows)+++# --------------------------------------------------------------------------+# xirr — recovery of a known rate+# --------------------------------------------------------------------------++[email protected]("rate", [-0.35, -0.05, 0.0, 0.0001, 0.1234, 0.85, 3.0])+def test_xirr_recovers_the_constructed_rate(rate):+ assert abs(xirr(constructed_schedule(rate)) - rate) < 1e-6+++def test_xirr_recovery_is_far_tighter_than_the_required_tolerance():+ # The bracketed solver closes to machine precision, not just to 1e-6.+ assert xirr(constructed_schedule(0.1234)) == pytest.approx(0.1234, abs=1e-12)+++def test_npv_at_the_solved_rate_is_zero():+ series = constructed_schedule(0.1234)+ assert npv(series, xirr(series)) == pytest.approx(0.0, abs=1e-9)+++def test_guess_cannot_move_the_bracketed_answer():+ series = constructed_schedule(0.1234)+ assert xirr(series, guess=-0.9) == xirr(series, guess=50.0) == xirr(series)+++# --------------------------------------------------------------------------+# xirr — annual dates must agree with the textbook IRR+# --------------------------------------------------------------------------+++def test_annual_dates_agree_with_textbook_irr():+ """365-day spacing must reproduce the equal-period IRR.++ The reference is the real root of ``sum(cf_i * x**i) == 0`` with+ ``x = 1/(1+r)``, found by ``np.roots`` -- a polynomial solver that shares no+ code with the module under test.+ """+ amounts = [-1000.0, 300.0, 400.0, 500.0, 200.0]+ start = dt.date(2020, 1, 1)+ rows = [+ (+ start + dt.timedelta(days=365 * index),+ amount,+ "purchase" if amount < 0 else "proceeds",+ )+ for index, amount in enumerate(amounts)+ ]++ roots = np.roots(amounts[::-1])+ real_positive = [+ root.real for root in roots if abs(root.imag) < 1e-12 and root.real > 0+ ]+ assert len(real_positive) == 1+ textbook_irr = 1.0 / real_positive[0] - 1.0++ assert xirr(make_series(rows), days_per_year=365.0) == pytest.approx(+ textbook_irr, abs=1e-9+ )+++def test_matches_the_published_excel_xirr_example():+ """Microsoft's documented XIRR worked example returns 0.373362535."""+ series = make_series(+ [+ ("2008-01-01", -10000.0, "purchase"),+ ("2008-03-01", 2750.0, "proceeds"),+ ("2008-10-30", 4250.0, "proceeds"),+ ("2009-02-15", 3250.0, "proceeds"),+ ("2009-04-01", 2750.0, "proceeds"),+ ]+ )+ assert xirr(series) == pytest.approx(0.373362535, abs=1e-8)+++# --------------------------------------------------------------------------+# xirr — refusals+# --------------------------------------------------------------------------+++def test_all_positive_series_raises_instead_of_returning_nonsense():+ series = make_series(+ [+ ("2020-01-01", 100.0, "distribution"),+ ("2021-01-01", 200.0, "distribution"),+ ("2022-01-01", 300.0, "distribution"),+ ]+ )+ with pytest.raises(NoSignChangeError):+ xirr(series)+++def test_all_negative_series_raises():+ series = make_series(+ [+ ("2020-01-01", -100.0, "capital_call"),+ ("2021-01-01", -200.0, "capital_call"),+ ]+ )+ with pytest.raises(NoSignChangeError):+ xirr(series)+++def test_no_sign_change_error_is_an_xirr_error_and_a_value_error():+ assert issubclass(NoSignChangeError, XIRRError)+ assert issubclass(XIRRError, ValueError)+++def test_all_zero_series_raises():+ series = make_series(+ [("2020-01-01", 0.0, "distribution"), ("2021-01-01", 0.0, "distribution")]+ )+ with pytest.raises(NoSignChangeError):+ xirr(series)+++def test_flows_on_a_single_date_raise():+ series = make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2020-01-01", 150.0, "distribution")]+ )+ with pytest.raises(ValueError, match="not identifiable"):+ xirr(series)+++def test_a_bare_list_of_floats_is_refused():+ with pytest.raises(TypeError, match="CashFlowSeries"):+ xirr([-1000.0, 400.0, 800.0])+++def test_rate_at_or_below_minus_one_is_refused_by_npv():+ with pytest.raises(ValueError, match="greater than -1"):+ npv(constructed_schedule(0.1), -1.0)+++# --------------------------------------------------------------------------+# xirr — valuation policy+# --------------------------------------------------------------------------+++FUND_ROWS = [+ ("2019-01-01", -600.0, "capital_call"),+ ("2019-07-01", -400.0, "capital_call"),+ ("2021-01-01", 250.0, "nav"),+ ("2021-06-01", 500.0, "distribution"),+ ("2023-01-01", 900.0, "distribution"),+ ("2023-06-30", 300.0, "nav"),+]+++def test_terminal_policy_uses_only_the_latest_mark():+ series = make_series(FUND_ROWS)+ explicit = make_series([row for row in FUND_ROWS if row[0] != "2021-01-01"])+ assert xirr(series) == pytest.approx(xirr(explicit, valuations="all"))+++def test_exclude_policy_drops_every_mark():+ series = make_series(FUND_ROWS)+ cash_only = make_series([row for row in FUND_ROWS if row[2] != "nav"])+ assert xirr(series, valuations="exclude") == pytest.approx(+ xirr(cash_only, valuations="all")+ )+++def test_including_residual_value_raises_the_irr():+ series = make_series(FUND_ROWS)+ assert xirr(series) > xirr(series, valuations="exclude")+++def test_unknown_valuation_policy_is_refused():+ with pytest.raises(ValueError, match="valuations="):+ xirr(make_series(FUND_ROWS), valuations="latest")+++def test_a_fund_with_no_distributions_still_has_an_irr_from_its_nav():+ series = make_series(+ [+ ("2020-01-01", -1000.0, "capital_call"),+ ("2023-01-01", 1500.0, "nav"),+ ]+ )+ years = (dt.date(2023, 1, 1) - dt.date(2020, 1, 1)).days / DAYS_PER_YEAR+ assert xirr(series) == pytest.approx(1.5 ** (1.0 / years) - 1.0, abs=1e-9)+++def test_xirr_all_returns_a_single_root_for_a_conventional_schedule():+ assert xirr_all(constructed_schedule(0.2)) == pytest.approx([0.2], abs=1e-9)+++def test_a_two_sign_change_schedule_reports_both_roots():+ """The textbook multiple-IRR pattern: out, in, out again.++ Two rates make the net present value zero, so reporting one of them as+ "the" IRR without saying so would be a hidden judgement call.+ """+ series = make_series(+ [+ ("2020-01-01", -100.0, "purchase"),+ ("2021-01-01", 230.0, "proceeds"),+ ("2022-01-01", -132.0, "purchase"),+ ]+ )+ roots = xirr_all(series)+ assert len(roots) == 2+ assert roots[0] < roots[1]+ for root in roots:+ assert npv(series, root) == pytest.approx(0.0, abs=1e-9)+ # Documented tie-break: the smallest root.+ assert xirr(series) == roots[0]+++def test_a_root_outside_the_requested_window_is_not_returned():+ """The Newton fallback must not smuggle a root past the caller's bounds.++ The real root of this schedule is about 2.9%. Asked to search only above+ 1000%, the scan finds nothing and Newton wanders back to 2.9% -- which is a+ genuine root but not one the caller asked for, so it is refused.+ """+ series = make_series(+ [("2019-03-15", -1428.0, "purchase"), ("2024-09-01", 1670.0, "proceeds")]+ )+ assert xirr(series) == pytest.approx(0.029026355, abs=1e-8)+ with pytest.raises(XIRRConvergenceError, match="not a root to tolerance"):+ xirr(series, rate_bounds=(10.0, 1.0e6))+++# --------------------------------------------------------------------------+# multiples+# --------------------------------------------------------------------------+++MULTIPLE_CASES = [+ FUND_ROWS,+ [+ ("2018-01-01", -1000.0, "capital_call"),+ ("2020-01-01", 1300.0, "distribution"),+ ],+ [+ ("2018-01-01", -250.0, "subscription"),+ ("2019-01-01", -750.0, "capital_call"),+ ("2022-01-01", 100.0, "dividend"),+ ("2023-01-01", 40.0, "proceeds"),+ ("2023-12-31", 1800.0, "nav"),+ ],+ [+ ("2021-01-01", -500.0, "capital_call"),+ ("2022-01-01", 120.0, "distribution"),+ ],+]++[email protected]("rows", MULTIPLE_CASES)+def test_tvpi_is_exactly_dpi_plus_rvpi(rows):+ series = make_series(rows)+ assert tvpi(series) == dpi(series) + rvpi(series)++[email protected]("rows", MULTIPLE_CASES)+def test_the_bundle_reports_the_same_identity(rows):+ result = fund_multiples(make_series(rows))+ assert isinstance(result, FundMultiples)+ assert result.tvpi == result.dpi + result.rvpi++[email protected]("rows", MULTIPLE_CASES)+def test_the_bundle_agrees_with_the_standalone_functions(rows):+ series = make_series(rows)+ result = fund_multiples(series)+ assert result.paid_in == pytest.approx(paid_in_capital(series))+ assert result.distributed == pytest.approx(distributed_capital(series))+ assert result.residual_value == pytest.approx(residual_value(series))+ assert result.dpi == pytest.approx(dpi(series))+ assert result.rvpi == pytest.approx(rvpi(series))+ assert result.tvpi == pytest.approx(tvpi(series))+ assert result.moic == pytest.approx(moic(series))+++def test_the_multiples_of_a_hand_computed_fund():+ # 1000 drawn, 1400 returned, 300 still on the books.+ series = make_series(+ [+ ("2018-01-01", -600.0, "capital_call"),+ ("2018-07-01", -400.0, "capital_call"),+ ("2021-01-01", 500.0, "distribution"),+ ("2022-01-01", 900.0, "distribution"),+ ("2022-12-31", 300.0, "nav"),+ ]+ )+ result = fund_multiples(series)+ assert result.paid_in == pytest.approx(1000.0)+ assert result.distributed == pytest.approx(1400.0)+ assert result.residual_value == pytest.approx(300.0)+ assert result.dpi == pytest.approx(1.4)+ assert result.rvpi == pytest.approx(0.3)+ assert result.tvpi == pytest.approx(1.7)+ assert result.moic == pytest.approx(1.7)+++def test_moic_equals_tvpi_on_paid_in_and_diverges_on_invested_capital():+ series = make_series(MULTIPLE_CASES[2])+ assert moic(series) == pytest.approx(tvpi(series))+ # Deal-level denominator: only the 750 actually deployed.+ assert moic(series, invested_capital=750.0) == pytest.approx(1940.0 / 750.0)+++def test_only_the_latest_mark_counts_as_residual_value():+ # Two marks; summing them would report 550 instead of 300.+ assert residual_value(make_series(FUND_ROWS)) == pytest.approx(300.0)+++def test_a_liquidated_fund_has_no_residual_value():+ series = make_series(+ [("2018-01-01", -100.0, "capital_call"), ("2020-01-01", 130.0, "distribution")]+ )+ assert residual_value(series) == 0.0+ assert rvpi(series) == 0.0+ assert tvpi(series) == pytest.approx(dpi(series))+++def test_contribution_kinds_are_a_parameter_not_a_hardcoded_set():+ series = make_series(+ [+ ("2020-01-01", -1000.0, "capital_call"),+ ("2020-06-01", -20.0, "fee"),+ ("2023-01-01", 1200.0, "distribution"),+ ]+ )+ assert paid_in_capital(series) == pytest.approx(1000.0)+ assert paid_in_capital(+ series, contribution_kinds=(*CONTRIBUTION_KINDS, "fee")+ ) == pytest.approx(1020.0)+++def test_a_fund_with_no_capital_drawn_has_no_multiple():+ series = make_series([("2020-01-01", 100.0, "distribution")])+ with pytest.raises(ValueError, match="undefined"):+ dpi(series)+++def test_a_negative_mark_is_refused_rather_than_guessed():+ series = CashFlowSeries(+ (+ CashFlow("2020-01-01", -100.0, "capital_call", "USD"),+ CashFlow("2021-01-01", -5.0, "nav", "USD"),+ )+ )+ with pytest.raises(ValueError, match="non-negative"):+ residual_value(series)+++def test_multiples_refuse_a_bare_list():+ with pytest.raises(TypeError, match="CashFlowSeries"):+ tvpi([-100.0, 150.0])+++# --------------------------------------------------------------------------+# waterfall — worked by hand+# --------------------------------------------------------------------------+++def test_the_worked_european_waterfall_example():+ """Hand-worked 8% pref / 20% carry / 100% catch-up on 150 distributable.++ Contributed capital 100, preferred owed 8, carry 20%, catch-up 100%::++ tier 1 return of capital 100 -> LP 100 remaining 50+ tier 2 preferred return 8 -> LP 8 remaining 42+ tier 3 GP catch-up C -> GP C+ C solves 1.00*C == 0.20*(8 + C) => C = 1.6/0.8 = 2+ 2 -> GP 2 remaining 40+ tier 4 carry split 40 -> GP 0.20*40 = 8, LP 32 remaining 0++ LP total = 100 + 8 + 0 + 32 = 140+ GP total = 0 + 0 + 2 + 8 = 10+ 140 + 10 = 150, the whole distributable amount.++ Profit distributed is 150 - 100 = 50, of which the GP took 10, i.e. exactly+ the 20% carry rate -- which is what a completed catch-up is for.+ """+ result = waterfall_split(+ 150.0, 100.0, 8.0, carry_rate=0.20, catch_up_rate=1.00+ )++ assert result.tier_amount(TIER_RETURN_OF_CAPITAL) == pytest.approx(100.0)+ assert result.tier_amount(TIER_PREFERRED_RETURN) == pytest.approx(8.0)+ assert result.tier_amount(TIER_CATCH_UP) == pytest.approx(2.0)+ assert result.tier_amount(TIER_CARRY_SPLIT) == pytest.approx(40.0)++ assert result.lp_total == pytest.approx(140.0)+ assert result.gp_total == pytest.approx(10.0)+ assert result.lp_total + result.gp_total == pytest.approx(150.0, abs=1e-12)+ assert sum(tier.amount for tier in result.tiers) == pytest.approx(+ 150.0, abs=1e-12+ )+ assert result.gp_profit_share == pytest.approx(0.20)+ assert result.unreturned_capital == 0.0+ assert result.unpaid_preferred == 0.0+++def test_a_partial_catch_up_rate_still_lands_the_gp_on_its_carry():+ """50% catch-up, 20% carry, pref 8, contributed 100, distributable 200.++ tier 1 return of capital 100 remaining 100+ tier 2 preferred return 8 remaining 92+ tier 3 catch-up C solves 0.50*C == 0.20*(8 + C) => C = 1.6/0.3+ C = 5.333333... -> GP 2.666667, LP 2.666667 remaining 86.666667+ tier 4 carry split 86.666667 -> GP 17.333333, LP 69.333333++ GP total = 2.666667 + 17.333333 = 20 = 20% of the 100 of profit.+ LP total = 100 + 8 + 2.666667 + 69.333333 = 180.+ """+ result = waterfall_split(200.0, 100.0, 8.0, carry_rate=0.20, catch_up_rate=0.50)+ assert result.tier_amount(TIER_CATCH_UP) == pytest.approx(1.6 / 0.3)+ assert result.gp_total == pytest.approx(20.0)+ assert result.lp_total == pytest.approx(180.0)+ assert result.gp_profit_share == pytest.approx(0.20)+++def test_no_catch_up_tier_leaves_the_gp_below_its_nominal_carry():+ """A hard hurdle: 20% carry applies only above the 8 of preferred.++ 100 returned, 8 preferred to LPs, then 92 split 20/80 -> GP 18.4, LP 73.6.+ GP takes 18.4 of the 100 of profit, i.e. 18.4%, not 20%.+ """+ result = waterfall_split(200.0, 100.0, 8.0, carry_rate=0.20, catch_up_rate=0.0)+ assert result.tier_amount(TIER_CATCH_UP) == 0.0+ assert result.gp_total == pytest.approx(18.4)+ assert result.lp_total == pytest.approx(181.6)+ assert result.gp_profit_share == pytest.approx(0.184)+++def test_an_incomplete_catch_up_keeps_the_gp_short():+ """Only 109 distributable: the catch-up tier is truncated at 1 of its 2."""+ result = waterfall_split(109.0, 100.0, 8.0, carry_rate=0.20, catch_up_rate=1.0)+ assert result.tier_amount(TIER_CATCH_UP) == pytest.approx(1.0)+ assert result.tier_amount(TIER_CARRY_SPLIT) == 0.0+ assert result.gp_total == pytest.approx(1.0)+ assert result.lp_total == pytest.approx(108.0)+ assert result.gp_profit_share == pytest.approx(1.0 / 9.0)+++def test_an_unmet_hurdle_pays_the_gp_nothing():+ result = waterfall_split(105.0, 100.0, 8.0, carry_rate=0.20, catch_up_rate=1.0)+ assert result.gp_total == 0.0+ assert result.lp_total == pytest.approx(105.0)+ assert result.unpaid_preferred == pytest.approx(3.0)+ assert result.unreturned_capital == 0.0+++def test_capital_not_yet_returned_is_reported():+ result = waterfall_split(60.0, 100.0, 8.0, carry_rate=0.20, catch_up_rate=1.0)+ assert result.unreturned_capital == pytest.approx(40.0)+ assert result.unpaid_preferred == pytest.approx(8.0)+ assert result.lp_total == pytest.approx(60.0)+ assert result.gp_total == 0.0+++ "distributable", [0.0, 1.0, 99.9, 100.0, 108.0, 110.0, 137.5, 1000.0]+)[email protected]("catch_up_rate", [0.0, 0.35, 0.5, 1.0])+def test_every_split_conserves_the_distributable_amount(distributable, catch_up_rate):+ result = waterfall_split(+ distributable, 100.0, 8.0, carry_rate=0.20, catch_up_rate=catch_up_rate+ )+ assert sum(tier.amount for tier in result.tiers) == pytest.approx(+ distributable, abs=1e-9+ )+ assert result.lp_total + result.gp_total == pytest.approx(+ distributable, abs=1e-9+ )+++def test_waterfall_rate_validation():+ with pytest.raises(ValueError, match="carry_rate"):+ waterfall_split(150.0, 100.0, 8.0, carry_rate=1.0)+ with pytest.raises(ValueError, match="catch_up_rate"):+ waterfall_split(150.0, 100.0, 8.0, carry_rate=0.2, catch_up_rate=1.5)+ with pytest.raises(ValueError, match="never complete"):+ waterfall_split(150.0, 100.0, 8.0, carry_rate=0.2, catch_up_rate=0.1)+ with pytest.raises(ValueError, match="non-negative"):+ waterfall_split(-1.0, 100.0, 8.0, carry_rate=0.2)+++def test_a_tier_that_does_not_conserve_cash_is_rejected_at_construction():+ with pytest.raises(ValueError, match="does not conserve cash"):+ WaterfallTier(name="bogus", amount=10.0, lp_amount=6.0, gp_amount=3.0)+++def test_a_result_whose_tiers_do_not_reconcile_is_rejected():+ tiers = (+ WaterfallTier(+ name=TIER_RETURN_OF_CAPITAL, amount=100.0, lp_amount=100.0, gp_amount=0.0+ ),+ )+ with pytest.raises(ValueError, match="does not reconcile"):+ WaterfallResult(+ distributable=150.0,+ contributed_capital=100.0,+ preferred_amount=8.0,+ tiers=tiers,+ lp_total=100.0,+ gp_total=0.0,+ unreturned_capital=0.0,+ unpaid_preferred=8.0,+ )+++# --------------------------------------------------------------------------+# preferred return + the series-driven waterfall+# --------------------------------------------------------------------------+++def test_simple_preferred_accrues_per_contribution_from_its_own_date():+ series = make_series(+ [+ ("2020-01-01", -100.0, "capital_call"),+ ("2021-01-01", -100.0, "capital_call"),+ ("2022-01-01", 0.0, "distribution"),+ ]+ )+ first_days = (dt.date(2022, 1, 1) - dt.date(2020, 1, 1)).days+ second_days = (dt.date(2022, 1, 1) - dt.date(2021, 1, 1)).days+ expected = 100.0 * 0.08 * (first_days / 365.0) + 100.0 * 0.08 * (+ second_days / 365.0+ )+ assert preferred_return_amount(+ series, rate=0.08, compounding="simple"+ ) == pytest.approx(expected)+++def test_a_later_draw_owes_less_hurdle_than_a_day_one_draw():+ early = make_series(+ [("2020-01-01", -200.0, "capital_call"), ("2025-01-01", 0.0, "distribution")]+ )+ late = make_series(+ [+ ("2020-01-01", -100.0, "capital_call"),+ ("2023-01-01", -100.0, "capital_call"),+ ("2025-01-01", 0.0, "distribution"),+ ]+ )+ assert preferred_return_amount(late, rate=0.08) < preferred_return_amount(+ early, rate=0.08+ )+++def test_compound_preferred_exceeds_simple_beyond_one_year():+ series = make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2025-01-01", 0.0, "distribution")]+ )+ assert preferred_return_amount(series, rate=0.08) > preferred_return_amount(+ series, rate=0.08, compounding="simple"+ )+++def test_a_zero_hurdle_accrues_nothing():+ series = make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2025-01-01", 0.0, "distribution")]+ )+ assert preferred_return_amount(series, rate=0.0) == 0.0+ assert preferred_return_amount(series, rate=0.0, compounding="simple") == 0.0+++def test_a_contribution_after_the_measurement_date_is_refused():+ series = make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2025-01-01", -50.0, "capital_call")]+ )+ with pytest.raises(ValueError, match="accrue backwards"):+ preferred_return_amount(series, rate=0.08, as_of="2021-01-01")+++def test_unknown_preferred_compounding_is_refused():+ series = make_series(+ [("2020-01-01", -100.0, "capital_call"), ("2025-01-01", 0.0, "distribution")]+ )+ with pytest.raises(ValueError, match="compounding="):+ preferred_return_amount(series, rate=0.08, compounding="continuous")+++def test_the_series_driven_waterfall_matches_the_hand_computed_split():+ """100 called 2020-01-01, 150 distributed 2022-01-01, 8% simple pref, 20/100.++ 2020 is a leap year, so the accrual spans 731 days::++ preferred = 100 * 0.08 * 731/365 = 16.021917808219176+ tier 1 return of capital 100 remaining 50+ tier 2 preferred 16.021918 remaining 33.978082+ tier 3 catch-up C = 0.2*16.021918/0.8 = 4.005479 -> GP 4.005479+ remaining 29.972603+ tier 4 carry split 29.972603 -> GP 5.994521, LP 23.978082++ GP total = 4.005479 + 5.994521 = 10 = 20% of the 50 of profit+ LP total = 150 - 10 = 140+ """+ series = make_series(+ [+ ("2020-01-01", -100.0, "capital_call"),+ ("2022-01-01", 150.0, "distribution"),+ ]+ )+ expected_preferred = 100.0 * 0.08 * (731.0 / 365.0)+ result = european_waterfall(+ series,+ preferred_rate=0.08,+ carry_rate=0.20,+ catch_up_rate=1.0,+ compounding="simple",+ )+ assert result.contributed_capital == pytest.approx(100.0)+ assert result.distributable == pytest.approx(150.0)+ assert result.preferred_amount == pytest.approx(expected_preferred)+ assert result.tier_amount(TIER_CATCH_UP) == pytest.approx(+ 0.2 * expected_preferred / 0.8+ )+ assert result.gp_total == pytest.approx(10.0)+ assert result.lp_total == pytest.approx(140.0)+ assert result.lp_total + result.gp_total == pytest.approx(150.0, abs=1e-12)+++def test_the_series_waterfall_distributes_realised_cash_by_default():+ series = make_series(+ [+ ("2020-01-01", -100.0, "capital_call"),+ ("2022-01-01", 40.0, "distribution"),+ ("2022-12-31", 200.0, "nav"),+ ]+ )+ realised = european_waterfall(series, preferred_rate=0.08, carry_rate=0.20)+ liquidated = european_waterfall(+ series, preferred_rate=0.08, carry_rate=0.20, include_residual=True+ )+ assert realised.distributable == pytest.approx(40.0)+ assert liquidated.distributable == pytest.approx(240.0)+ assert realised.gp_total == 0.0+ assert liquidated.gp_total > 0.0+++def test_the_series_waterfall_refuses_a_bare_list():+ with pytest.raises(TypeError, match="CashFlowSeries"):+ european_waterfall([-100.0, 150.0], preferred_rate=0.08, carry_rate=0.2)diff --git a/agent/tests/quantlib/test_performance.py b/agent/tests/quantlib/test_performance.pynew file mode 100644index 000000000..c95a6fa0d--- /dev/null+++ b/agent/tests/quantlib/test_performance.py@@ -0,0 +1,407 @@+"""Tests for client-cash-flow-aware performance measurement.++The load-bearing property is the one TWR exists for: chain-linking must be+invariant to the size and the date of an external contribution, while the+money-weighted return must *not* be. Both are asserted against the same+underlying return path, so a divergence can only come from the flow.+"""++from __future__ import annotations++import math+from datetime import date++import pytest++from src.entities.cashflow import CashFlow, CashFlowSeries+from src.quantlib.performance import (+ DEFAULT_EXTERNAL_KINDS,+ FLOW_TIMING_END,+ FLOW_TIMING_START,+ UnsolvableRateError,+ external_flows,+ modified_dietz_return,+ money_weighted_return,+ time_weighted_return,+ xirr,+)++USD = "USD"+++def _build_valuations(+ dates: list[date],+ returns: list[float],+ flows: dict[date, float] | None = None,+) -> list[tuple[date, float]]:+ """Roll a known return path forward, injecting end-of-period client cash.++ ``V_k = V_{k-1} * (1 + r_k) + F_k`` is exactly the accounting the+ ``flow_timing="end"`` convention describes, so any TWR computed from the+ result must recover ``prod(1 + r_k) - 1`` no matter what ``F_k`` was.++ Args:+ dates: Valuation dates, earliest first; one more than ``returns``.+ returns: Return of each interval between consecutive dates.+ flows: Portfolio-perspective cash arriving on a valuation date.++ Returns:+ ``(date, value)`` pairs starting at 100.0.+ """+ injections = flows or {}+ value = 100.0+ series = [(dates[0], value)]+ for index, period_return in enumerate(returns, start=1):+ value = value * (1.0 + period_return) + injections.get(dates[index], 0.0)+ series.append((dates[index], value))+ return series+++_PATH_DATES = [+ date(2024, 1, 1),+ date(2024, 4, 1),+ date(2024, 7, 1),+ date(2024, 10, 1),+ date(2024, 12, 31),+]+_PATH_RETURNS = [0.08, -0.05, 0.12, -0.03]+++def _contribution(when: date, size: float) -> CashFlowSeries:+ """Wrap one client contribution of ``size`` in a series.++ The amount is negated because ``CashFlow`` is holder-perspective: money the+ client pays into the account leaves the client's pocket.++ Args:+ when: Date the contribution settles.+ size: Positive size of the money arriving in the portfolio.++ Returns:+ A single-flow ``CashFlowSeries`` in USD.+ """+ return CashFlowSeries((CashFlow(when, -size, "contribution", USD),))+++# ─── The defining TWR property ───+++def test_twr_is_invariant_to_the_size_and_date_of_a_contribution() -> None:+ """Same return path, three different flow schedules, one TWR."""+ expected = math.prod(1.0 + r for r in _PATH_RETURNS) - 1.0++ unflowed = time_weighted_return(_build_valuations(_PATH_DATES, _PATH_RETURNS))+ small_early = time_weighted_return(+ _build_valuations(_PATH_DATES, _PATH_RETURNS, {date(2024, 4, 1): 50.0}),+ _contribution(date(2024, 4, 1), 50.0),+ )+ huge_late = time_weighted_return(+ _build_valuations(_PATH_DATES, _PATH_RETURNS, {date(2024, 10, 1): 500_000.0}),+ _contribution(date(2024, 10, 1), 500_000.0),+ )++ assert unflowed.total_return == pytest.approx(expected, rel=1e-12)+ assert small_early.total_return == pytest.approx(expected, rel=1e-12)+ assert huge_late.total_return == pytest.approx(expected, rel=1e-12)+ # A 500k injection into a 100-unit account changes the end value by four+ # orders of magnitude and still cannot move the return.+ assert huge_late.end_value > 400_000.0+ assert unflowed.end_value < 200.0+++def test_twr_and_mwr_provably_differ_when_money_arrives_before_a_drawdown() -> None:+ """A contribution timed into the loss hurts the client, not the manager."""+ valuations = [+ (date(2024, 1, 1), 100.0),+ (date(2024, 7, 1), 1010.0), # +10% on 100, then 900 arrives+ (date(2024, 12, 31), 909.0), # -10% on 1010+ ]+ flows = _contribution(date(2024, 7, 1), 900.0)++ twr = time_weighted_return(valuations, flows)+ mwr = money_weighted_return(valuations, flows)++ # 1.10 * 0.90 - 1 = -1% exactly, whatever the client did.+ assert twr.total_return == pytest.approx(-0.01, abs=1e-12)+ assert [period.period_return for period in twr.sub_periods] == pytest.approx(+ [0.10, -0.10], abs=1e-12+ )+ # The client had 100 in the gain and 1010 in the loss, so their own money+ # did far worse than the manager's unit of capital.+ assert mwr.annualized_return == pytest.approx(-0.15943701746, rel=1e-9)+ assert mwr.period_return < twr.total_return - 0.10+ assert mwr.net_external_flow == pytest.approx(900.0)+++def test_twr_equals_the_simple_return_when_nothing_moves() -> None:+ """With no external flow the chain-link collapses to end over start."""+ valuations = [+ (date(2024, 1, 1), 250_000.0),+ (date(2024, 6, 30), 262_500.0),+ (date(2024, 12, 31), 300_000.0),+ ]+ simple = valuations[-1][1] / valuations[0][1] - 1.0++ twr = time_weighted_return(valuations)+ dietz = modified_dietz_return(valuations)++ assert twr.total_return == pytest.approx(simple, rel=1e-15)+ assert twr.net_external_flow == 0.0+ # Modified Dietz has no flows to weight, so its denominator is just V0 and+ # it must agree exactly with the same simple return.+ assert dietz.total_return == pytest.approx(simple, rel=1e-15)+ assert dietz.average_capital == 250_000.0+++def test_two_point_no_flow_twr_is_exactly_the_price_relative() -> None:+ """A single interval must not introduce any compounding error at all."""+ valuations = [(date(2024, 1, 1), 400.0), (date(2024, 12, 31), 520.0)]+ twr = time_weighted_return(valuations)+ assert twr.total_return == 520.0 / 400.0 - 1.0+++# ─── Modified Dietz ───+++def test_modified_dietz_matches_the_hand_computed_example() -> None:+ """100k grows to 130k with 20k added on 1 Jul 2024; R = 9.088645%.++ By hand, on a 365-day period (1 Jan 2024 to 31 Dec 2024):+ D = (1 Jul - 1 Jan) = 182 days, so w = (365 - 182) / 365 = 183/365+ F = +20,000 into the portfolio+ R = (130,000 - 100,000 - 20,000) / (100,000 + 20,000 * 183/365)+ = 10,000 / 110,027.39726027397+ = 0.09088645418326692+ """+ result = modified_dietz_return(+ [(date(2024, 1, 1), 100_000.0), (date(2024, 12, 31), 130_000.0)],+ _contribution(date(2024, 7, 1), 20_000.0),+ )++ weight = 183 / 365+ assert (date(2024, 12, 31) - date(2024, 1, 1)).days == 365+ assert result.flow_weights == ((date(2024, 7, 1), 20_000.0, weight),)+ assert result.weighted_external_flow == pytest.approx(20_000.0 * weight)+ assert result.average_capital == pytest.approx(100_000.0 + 20_000.0 * weight)+ assert result.total_return == pytest.approx(+ 10_000.0 / (100_000.0 + 20_000.0 * weight), rel=1e-15+ )+ assert round(result.total_return, 8) == 0.09088645+++def test_modified_dietz_weights_run_from_one_to_zero() -> None:+ """A flow on the opening day is fully invested; one on the closing day is not."""+ flows = CashFlowSeries(+ (+ CashFlow(date(2024, 1, 1), -1_000.0, "contribution", USD),+ CashFlow(date(2024, 12, 31), -1_000.0, "contribution", USD),+ )+ )+ result = modified_dietz_return(+ [(date(2024, 1, 1), 10_000.0), (date(2024, 12, 31), 12_000.0)], flows+ )+ assert [weight for _, _, weight in result.flow_weights] == [1.0, 0.0]+ assert result.average_capital == pytest.approx(11_000.0)+++def test_modified_dietz_is_flow_timing_sensitive_where_twr_is_not() -> None:+ """The two measures must not agree once a mid-period flow exists."""+ valuations = [+ (date(2024, 1, 1), 100.0),+ (date(2024, 7, 1), 1010.0),+ (date(2024, 12, 31), 909.0),+ ]+ flows = _contribution(date(2024, 7, 1), 900.0)+ twr = time_weighted_return(valuations, flows)+ dietz = modified_dietz_return(valuations, flows)+ assert dietz.total_return != pytest.approx(twr.total_return, abs=1e-6)+ assert dietz.total_return < 0.0+++# ─── Flow classification ───+++def test_only_boundary_crossing_kinds_are_treated_as_external() -> None:+ """A dividend is already inside the valuation and must not be netted out."""+ flows = CashFlowSeries(+ (+ CashFlow(date(2024, 7, 1), -500.0, "contribution", USD),+ CashFlow(date(2024, 8, 1), 40.0, "dividend", USD),+ CashFlow(date(2024, 9, 1), -12.0, "fee", USD),+ CashFlow(date(2024, 10, 1), 250_000.0, "nav", USD),+ )+ )+ selected = external_flows(flows)+ assert selected == ((date(2024, 7, 1), 500.0),)+ assert "dividend" not in DEFAULT_EXTERNAL_KINDS+++def test_an_unclassified_kind_is_refused_rather_than_assumed() -> None:+ """Silently ignoring an unknown kind would return a plausible wrong number."""+ flows = CashFlowSeries((CashFlow(date(2024, 7, 1), -500.0, "wire_in", USD),))+ with pytest.raises(ValueError, match="neither external nor internal"):+ external_flows(flows)++ reclassified = external_flows(flows, external_kinds=["wire_in"])+ assert reclassified == ((date(2024, 7, 1), 500.0),)+++def test_a_kind_cannot_be_both_external_and_internal() -> None:+ """Contradictory classification is an error, not a precedence puzzle."""+ with pytest.raises(ValueError, match="cannot be both"):+ external_flows(+ CashFlowSeries(()),+ external_kinds=["contribution"],+ internal_kinds=["contribution"],+ )+++# ─── Flow timing ───+++def test_start_timing_invests_the_flow_for_the_whole_interval() -> None:+ """Under start timing the same numbers give a different, exact answer."""+ valuations = [(date(2024, 1, 1), 100.0), (date(2024, 7, 1), 220.0)]+ flows = CashFlowSeries((CashFlow(date(2024, 1, 1), -100.0, "contribution", USD),))+ result = time_weighted_return(valuations, flows, flow_timing=FLOW_TIMING_START)+ # 200 invested at the open, worth 220 at the close.+ assert result.total_return == pytest.approx(0.10, abs=1e-15)+ assert result.flow_timing == FLOW_TIMING_START+++def test_a_flow_outside_the_valuation_window_is_an_error() -> None:+ """Dropping it would move client money into the manager's return."""+ valuations = [(date(2024, 1, 1), 100.0), (date(2024, 12, 31), 120.0)]+ flows = _contribution(date(2025, 3, 1), 10.0)+ with pytest.raises(ValueError, match="outside the valuation window"):+ time_weighted_return(valuations, flows)+++def test_end_timing_refuses_a_flow_on_the_opening_valuation() -> None:+ """It would already be inside V0, so counting it again double-counts."""+ valuations = [(date(2024, 1, 1), 100.0), (date(2024, 12, 31), 120.0)]+ flows = _contribution(date(2024, 1, 1), 10.0)+ with pytest.raises(ValueError, match="coincides with the opening valuation"):+ time_weighted_return(valuations, flows, flow_timing=FLOW_TIMING_END)+++def test_an_unknown_flow_timing_token_is_rejected() -> None:+ """A typo must not silently select the default convention."""+ with pytest.raises(ValueError, match="flow_timing must be"):+ time_weighted_return(+ [(date(2024, 1, 1), 100.0), (date(2024, 12, 31), 120.0)],+ flow_timing="middle",+ )+++# ─── Validation ───+++def test_a_single_valuation_cannot_produce_a_return() -> None:+ """An opening and a closing mark are both required."""+ with pytest.raises(ValueError, match="opening and a closing valuation"):+ time_weighted_return([(date(2024, 1, 1), 100.0)])+++def test_duplicate_valuation_dates_are_rejected() -> None:+ """Two marks for one day have no defensible ordering."""+ with pytest.raises(ValueError, match="share the date"):+ time_weighted_return(+ [+ (date(2024, 1, 1), 100.0),+ (date(2024, 1, 1), 101.0),+ (date(2024, 6, 1), 110.0),+ ]+ )+++def test_a_non_positive_invested_base_has_no_honest_return() -> None:+ """An account at zero did not 'return' anything on the way back."""+ with pytest.raises(ValueError, match="invested base"):+ time_weighted_return(+ [(date(2024, 1, 1), 0.0), (date(2024, 6, 1), 50.0)]+ )+++def test_iso_strings_and_mappings_are_accepted_like_dates() -> None:+ """Normalisation is reused from the entity spine, not re-implemented."""+ from_pairs = time_weighted_return(+ [("2024-01-01", 100.0), ("2024-12-31", 130.0)]+ )+ from_mapping = time_weighted_return(+ {date(2024, 12, 31): 130.0, date(2024, 1, 1): 100.0}+ )+ assert from_pairs.total_return == pytest.approx(0.30)+ assert from_mapping.total_return == pytest.approx(0.30)+ assert from_mapping.start_date == date(2024, 1, 1)+++# ─── XIRR ───+++def test_xirr_recovers_a_known_flat_rate() -> None:+ """Pay 1000, receive 1100 exactly one year later: 10%."""+ rate = xirr([(date(2024, 1, 1), -1000.0), (date(2024, 12, 31), 1100.0)])+ # 365 days on a 365-day basis is exactly one year.+ assert rate == pytest.approx(0.10, abs=1e-9)+++def test_xirr_discounts_by_actual_days() -> None:+ """Half the elapsed time at the same multiple must roughly square the rate."""+ half_year = xirr([(date(2024, 1, 1), -1000.0), (date(2024, 7, 1), 1100.0)])+ assert (1.0 + half_year) ** (182 / 365) == pytest.approx(1.10, rel=1e-6)+++def test_a_one_directional_stream_has_no_irr() -> None:+ """Refusing is correct; there is no rate that zeroes an all-negative NPV."""+ with pytest.raises(UnsolvableRateError, match="one-directional"):+ xirr([(date(2024, 1, 1), -1000.0), (date(2024, 12, 31), -500.0)])+++def test_money_weighted_return_with_no_flows_is_just_annualised_growth() -> None:+ """With no client activity the IRR reduces to the account's own growth."""+ result = money_weighted_return(+ [(date(2024, 1, 1), 1000.0), (date(2024, 12, 31), 1210.0)]+ )+ assert result.annualized_return == pytest.approx(0.21, abs=1e-9)+ assert result.period_return == pytest.approx(0.21, abs=1e-9)+ assert result.net_external_flow == 0.0+++def test_money_weighted_return_ignores_interim_marks() -> None:+ """An IRR is determined by cash; revaluing midway cannot change it."""+ flows = _contribution(date(2024, 7, 1), 500.0)+ sparse = money_weighted_return(+ [(date(2024, 1, 1), 1000.0), (date(2024, 12, 31), 1800.0)], flows+ )+ dense = money_weighted_return(+ [+ (date(2024, 1, 1), 1000.0),+ (date(2024, 5, 1), 1234.0),+ (date(2024, 9, 30), 1700.0),+ (date(2024, 12, 31), 1800.0),+ ],+ flows,+ )+ assert dense.annualized_return == pytest.approx(sparse.annualized_return, rel=1e-9)+++# ─── Annualisation ───+++def test_a_sub_year_window_is_not_annualised() -> None:+ """Stating a full-year figure that was never observed is extrapolation."""+ short = time_weighted_return(+ [(date(2024, 1, 1), 100.0), (date(2024, 3, 31), 110.0)]+ )+ assert short.total_return == pytest.approx(0.10)+ assert short.annualized_return is None+++def test_a_multi_year_window_is_annualised_geometrically() -> None:+ """Two years of doubling annualises to sqrt(2) - 1."""+ result = time_weighted_return(+ [(date(2023, 1, 1), 100.0), (date(2025, 1, 1), 200.0)]+ )+ days = (date(2025, 1, 1) - date(2023, 1, 1)).days+ assert result.annualized_return == pytest.approx(2.0 ** (365 / days) - 1.0)diff --git a/agent/tests/test_cashflow_analytics_tool.py b/agent/tests/test_cashflow_analytics_tool.pynew file mode 100644index 000000000..0fdca22c9--- /dev/null+++ b/agent/tests/test_cashflow_analytics_tool.py@@ -0,0 +1,237 @@+"""Tests for the agent-facing cashflow_performance tool envelope."""++from __future__ import annotations++import json+from pathlib import Path++import pytest++from src.tools.cashflow_analytics_tool import CashFlowPerformanceTool+++def _valuations() -> list[dict[str, object]]:+ """Return the fixture path: +10% on 100, 900 arrives, then -10%."""+ return [+ {"date": "2024-01-01", "value": 100.0},+ {"date": "2024-07-01", "value": 1010.0},+ {"date": "2024-12-31", "value": 909.0},+ ]+++def _inline_contribution() -> list[dict[str, object]]:+ """Return the matching client contribution, holder-perspective."""+ return [+ {+ "date": "2024-07-01",+ "amount": -900.0,+ "kind": "contribution",+ "currency": "USD",+ }+ ]+++def _write_flow_file(tmp_path: Path) -> Path:+ """Write a two-row broker-style cash-flow CSV.++ Args:+ tmp_path: pytest temporary directory.++ Returns:+ Path to the written file.+ """+ path = tmp_path / "client_flows.csv"+ path.write_text(+ "date,amount,kind,currency\n"+ "2024-07-01,-900.00,contribution,USD\n"+ "2024-09-01,40.00,dividend,USD\n",+ encoding="utf-8",+ )+ return path+++def test_envelope_reports_all_three_measures_and_their_workings() -> None:+ """The success envelope is well formed, serializable, and self-auditing."""+ payload = json.loads(+ CashFlowPerformanceTool().execute(+ valuations=_valuations(),+ flows=_inline_contribution(),+ )+ )++ assert payload["status"] == "ok"+ assert payload["tool"] == "cashflow_performance"+ assert payload["inputs"]["flow_source"] == "inline"+ assert payload["inputs"]["currency"] == "USD"+ assert payload["inputs"]["flow_timing"] == "end"++ summary = payload["summary"]+ assert summary["start_date"] == "2024-01-01"+ assert summary["end_date"] == "2024-12-31"+ assert summary["net_external_flow"] == pytest.approx(900.0)+ assert summary["time_weighted_return"] == pytest.approx(-0.01, abs=1e-9)+ # The client's own money was far worse off than the manager's unit of capital.+ assert summary["money_weighted_return_annualized"] < -0.10+ assert summary["modified_dietz_return"] < -0.10++ assert [period["return"] for period in payload["sub_periods"]] == pytest.approx(+ [0.10, -0.10], abs=1e-9+ )+ assert payload["modified_dietz"]["flow_weights"] == [+ {"date": "2024-07-01", "amount": 900.0, "weight": pytest.approx(0.50137, abs=1e-5)}+ ]+ assert payload["money_weighted"]["solver_iterations"] > 0+ assert payload["notes"] == []+ assert payload["limitations"]+++def test_flows_can_be_loaded_from_a_file_and_internal_kinds_are_ignored(+ tmp_path: Path,+) -> None:+ """A dividend row sits inside the valuations and must not be netted out."""+ payload = json.loads(+ CashFlowPerformanceTool().execute(+ valuations=_valuations(),+ flows_path=str(_write_flow_file(tmp_path)),+ )+ )++ assert payload["status"] == "ok"+ assert payload["inputs"]["flow_source"] == "flows_path"+ assert payload["inputs"]["flow_count"] == 2+ # Two rows read, one external: the dividend is internal.+ assert payload["summary"]["net_external_flow"] == pytest.approx(900.0)+ assert payload["summary"]["time_weighted_return"] == pytest.approx(-0.01, abs=1e-9)+++def test_a_bad_path_returns_a_clean_error_envelope(tmp_path: Path) -> None:+ """A missing file is an explicit error, never a silent null result."""+ payload = json.loads(+ CashFlowPerformanceTool().execute(+ valuations=_valuations(),+ flows_path=str(tmp_path / "does_not_exist.csv"),+ )+ )++ assert payload["status"] == "error"+ assert payload["tool"] == "cashflow_performance"+ assert "does_not_exist.csv" in payload["error"]+ assert "money_weighted" not in payload+++ ("kwargs", "fragment"),+ [+ ({"valuations": [{"date": "2024-01-01", "value": 100.0}]}, "at least two"),+ ({"valuations": _valuations(), "flow_timing": "middle"}, "flow_timing must be"),+ (+ {+ "valuations": _valuations(),+ "flows": _inline_contribution(),+ "flows_path": "somewhere.csv",+ },+ "not both",+ ),+ (+ {+ "valuations": _valuations(),+ "flows": [{"date": "2024-07-01", "amount": -900.0, "kind": "contribution"}],+ },+ "no currency",+ ),+ (+ {+ "valuations": _valuations(),+ "flows": [+ {+ "date": "2024-07-01",+ "amount": 900.0,+ "kind": "contribution",+ "currency": "USD",+ }+ ],+ },+ "negative (cash out)",+ ),+ (+ {+ "valuations": _valuations(),+ "flows": [+ {+ "date": "2024-07-01",+ "amount": -900.0,+ "kind": "wire_in",+ "currency": "USD",+ }+ ],+ },+ "neither external nor internal",+ ),+ ],+)+def test_invalid_input_returns_an_error_envelope(+ kwargs: dict[str, object], fragment: str+) -> None:+ """Every rejection path produces the same shape, with a usable message."""+ payload = json.loads(CashFlowPerformanceTool().execute(**kwargs))+ assert payload["status"] == "error"+ assert fragment in payload["error"]+++def test_reclassifying_a_custom_kind_makes_it_external() -> None:+ """The escape hatch from the unclassified-kind error actually works."""+ payload = json.loads(+ CashFlowPerformanceTool().execute(+ valuations=_valuations(),+ flows=[+ {+ "date": "2024-07-01",+ "amount": -900.0,+ "kind": "wire_in",+ "currency": "USD",+ }+ ],+ external_kinds=["wire_in"],+ )+ )+ assert payload["status"] == "ok"+ assert payload["summary"]["net_external_flow"] == pytest.approx(900.0)+ assert "wire_in" in payload["inputs"]["external_kinds"]+++def test_an_unsolvable_irr_is_reported_as_a_note_not_a_failure() -> None:+ """A total loss with no distributions has no IRR; the rest still ships."""+ payload = json.loads(+ CashFlowPerformanceTool().execute(+ valuations=[+ {"date": "2024-01-01", "value": 1000.0},+ {"date": "2024-12-31", "value": 0.0},+ ]+ )+ )++ assert payload["status"] == "ok"+ assert payload["summary"]["time_weighted_return"] == -1.0+ assert payload["summary"]["modified_dietz_return"] == -1.0+ assert payload["summary"]["money_weighted_return_annualized"] is None+ assert payload["money_weighted"] is None+ assert any("one-directional" in note for note in payload["notes"])+++def test_the_tool_is_auto_discovered_by_the_agent_registry() -> None:+ """Creating the module is sufficient to expose the read-only agent tool."""+ from src.tools import build_registry++ registry = build_registry()+ tool = registry.get("cashflow_performance")+ assert tool is not None+ assert tool.is_readonly is True+++def test_the_tool_places_no_orders() -> None:+ """Guard the red line: this is a research surface with no execution path."""+ from src.tools import cashflow_analytics_tool++ source = Path(cashflow_analytics_tool.__file__).read_text(encoding="utf-8")+ assert "place_order" not in source+ assert "cancel_order" not in sourcediff --git a/agent/tests/test_entities_spine.py b/agent/tests/test_entities_spine.pynew file mode 100644index 000000000..46e291bea--- /dev/null+++ b/agent/tests/test_entities_spine.py@@ -0,0 +1,673 @@+"""Unit tests for the entity and irregular cash-flow spine."""++from __future__ import annotations++import dataclasses+from datetime import date, datetime++import pytest++from src.entities.cashflow import (+ CashFlow,+ CashFlowSeries,+ CurrencyMismatchError,+ normalize_kind,+)+from src.entities.ingest import CashFlowIngestError, load_cashflows+from src.entities.models import (+ Bond,+ Entity,+ EntityType,+ Fund,+ FundStructure,+ Instrument,+ Security,+ SecurityType,+)+++# ---------------------------------------------------------------------------+# Helpers+# ---------------------------------------------------------------------------+++def _flow(day: int, amount: float, kind: str = "coupon", currency: str = "USD") -> CashFlow:+ """Build a CashFlow on 2024-01-<day> for terse test construction."""+ return CashFlow(date=date(2024, 1, day), amount=amount, kind=kind, currency=currency)+++def _write_csv(tmp_path, name: str, text: str, encoding: str = "utf-8"):+ """Write a fixture file and return its path."""+ path = tmp_path / name+ path.write_text(text, encoding=encoding)+ return path+++# ---------------------------------------------------------------------------+# CashFlow construction and immutability+# ---------------------------------------------------------------------------+++def test_cashflow_constructs_and_normalizes():+ flow = CashFlow(date="2024-03-05", amount=-1000, kind="Capital Call", currency=" usd ")+ assert flow.date == date(2024, 3, 5)+ assert flow.amount == -1000.0+ assert isinstance(flow.amount, float)+ assert flow.kind == "capital_call"+ assert flow.currency == "USD"+++def test_cashflow_accepts_datetime_and_truncates_to_date():+ flow = CashFlow(+ date=datetime(2024, 3, 5, 16, 30), amount=10.0, kind="coupon", currency="USD"+ )+ assert flow.date == date(2024, 3, 5)+ assert not isinstance(flow.date, datetime)+++def test_cashflow_is_immutable():+ flow = _flow(1, 100.0)+ with pytest.raises(dataclasses.FrozenInstanceError):+ flow.amount = 999.0+++def test_cashflow_metadata_is_read_only():+ flow = CashFlow(+ date=date(2024, 1, 1),+ amount=100.0,+ kind="coupon",+ currency="USD",+ metadata={"note": "semi-annual"},+ )+ assert flow.metadata["note"] == "semi-annual"+ with pytest.raises(TypeError):+ flow.metadata["note"] = "tampered"+++def test_cashflow_metadata_copies_input_so_later_mutation_cannot_leak_in():+ source = {"note": "original"}+ flow = CashFlow(+ date=date(2024, 1, 1),+ amount=100.0,+ kind="coupon",+ currency="USD",+ metadata=source,+ )+ source["note"] = "changed after construction"+ assert flow.metadata["note"] == "original"+++def test_cashflow_rejects_missing_currency():+ with pytest.raises(ValueError, match="currency is required"):+ CashFlow(date=date(2024, 1, 1), amount=1.0, kind="coupon", currency="")+++def test_cashflow_rejects_non_finite_amount():+ with pytest.raises(ValueError, match="finite"):+ CashFlow(date=date(2024, 1, 1), amount=float("nan"), kind="coupon", currency="USD")+++def test_cashflow_rejects_ambiguous_date_string():+ with pytest.raises(ValueError, match="ISO-8601"):+ CashFlow(date="03/04/2024", amount=1.0, kind="coupon", currency="USD")+++# ---------------------------------------------------------------------------+# Sign convention -- enforced centrally, not by each caller+# ---------------------------------------------------------------------------+++def test_sign_convention_rejects_positive_capital_call():+ with pytest.raises(ValueError, match="negative"):+ CashFlow(date=date(2024, 1, 1), amount=1000.0, kind="capital_call", currency="USD")+++def test_sign_convention_rejects_negative_distribution():+ with pytest.raises(ValueError, match="positive"):+ CashFlow(date=date(2024, 1, 1), amount=-500.0, kind="distribution", currency="USD")+++def test_sign_convention_applies_after_kind_normalization():+ """'Capital Call' must be checked as capital_call, not treated as custom."""+ with pytest.raises(ValueError, match="negative"):+ CashFlow(date=date(2024, 1, 1), amount=1000.0, kind="Capital Call", currency="USD")+++def test_custom_kind_carries_no_sign_constraint():+ """The documented escape hatch: name the flow, do not disable the check."""+ clawback = CashFlow(+ date=date(2024, 1, 1),+ amount=-250.0,+ kind="recallable_distribution",+ currency="USD",+ )+ assert clawback.amount == -250.0+++def test_zero_amount_is_allowed_for_a_signed_kind():+ waived = CashFlow(date=date(2024, 1, 1), amount=0.0, kind="fee", currency="USD")+ assert waived.amount == 0.0+++def test_normalize_kind_collapses_separators():+ assert normalize_kind(" Capital -- Call ") == "capital_call"+++# ---------------------------------------------------------------------------+# Ordering+# ---------------------------------------------------------------------------+++def test_series_orders_by_date():+ series = CashFlowSeries(flows=(_flow(10, 1.0), _flow(2, 2.0), _flow(7, 3.0)))+ assert series.dates() == (date(2024, 1, 2), date(2024, 1, 7), date(2024, 1, 10))+ assert series.amounts() == (2.0, 3.0, 1.0)+++def test_series_ordering_is_stable_within_a_date():+ first = _flow(5, -100.0, kind="capital_call")+ second = _flow(5, 400.0, kind="distribution")+ series = CashFlowSeries(flows=(first, second))+ assert list(series) == [first, second]+++def test_series_is_immutable():+ series = CashFlowSeries(flows=(_flow(1, 1.0),))+ with pytest.raises(dataclasses.FrozenInstanceError):+ series.flows = ()+ assert isinstance(series.flows, tuple)+++# ---------------------------------------------------------------------------+# Currency coherence+# ---------------------------------------------------------------------------+++def test_series_rejects_mixed_currencies():+ with pytest.raises(CurrencyMismatchError, match="multiple currencies"):+ CashFlowSeries(flows=(_flow(1, 1.0, currency="USD"), _flow(2, 1.0, currency="EUR")))+++def test_series_infers_currency_from_its_flows():+ series = CashFlowSeries(flows=(_flow(1, 1.0, currency="jpy"),))+ assert series.currency == "JPY"+++def test_series_rejects_declared_currency_contradicting_the_flows():+ with pytest.raises(CurrencyMismatchError, match="does not match"):+ CashFlowSeries(flows=(_flow(1, 1.0, currency="USD"),), currency="EUR")+++def test_pre_translated_allows_mixed_currencies_when_told_explicitly():+ series = CashFlowSeries(+ flows=(_flow(1, 1.0, currency="USD"), _flow(2, 2.0, currency="EUR")),+ currency="USD",+ pre_translated=True,+ )+ assert series.currency == "USD"+ assert series.total() == pytest.approx(3.0)+++def test_pre_translated_without_a_reporting_currency_is_refused():+ with pytest.raises(ValueError, match="reporting currency must be named"):+ CashFlowSeries(+ flows=(_flow(1, 1.0, currency="USD"), _flow(2, 2.0, currency="EUR")),+ pre_translated=True,+ )+++# ---------------------------------------------------------------------------+# filter / between / total+# ---------------------------------------------------------------------------+++def test_filter_by_single_and_multiple_kinds():+ series = CashFlowSeries(+ flows=(+ _flow(1, -100.0, kind="capital_call"),+ _flow(2, 50.0, kind="distribution"),+ _flow(3, 10.0, kind="coupon"),+ )+ )+ assert len(series.filter(kind="coupon")) == 1+ assert series.filter(kind="Capital Call").amounts() == (-100.0,)+ assert len(series.filter(kind=["coupon", "distribution"])) == 2+++def test_filter_preserves_currency_even_when_it_empties_the_series():+ series = CashFlowSeries(flows=(_flow(1, 10.0, currency="EUR"),))+ empty = series.filter(kind="capital_call")+ assert empty.is_empty+ assert empty.currency == "EUR"+++def test_between_is_inclusive_on_both_ends():+ series = CashFlowSeries(flows=(_flow(1, 1.0), _flow(5, 2.0), _flow(9, 3.0)))+ window = series.between(date(2024, 1, 5), date(2024, 1, 9))+ assert window.amounts() == (2.0, 3.0)+++def test_between_accepts_open_ends_and_iso_strings():+ series = CashFlowSeries(flows=(_flow(1, 1.0), _flow(5, 2.0), _flow(9, 3.0)))+ assert series.between(end="2024-01-05").amounts() == (1.0, 2.0)+ assert series.between(start="2024-01-05").amounts() == (2.0, 3.0)+ assert series.between().amounts() == (1.0, 2.0, 3.0)+++def test_between_rejects_a_reversed_window():+ series = CashFlowSeries(flows=(_flow(1, 1.0),))+ with pytest.raises(ValueError, match="is after end"):+ series.between(date(2024, 1, 9), date(2024, 1, 1))+++def test_total_sums_signed_amounts():+ series = CashFlowSeries(+ flows=(_flow(1, -1000.0, kind="capital_call"), _flow(2, 250.0, kind="distribution"))+ )+ assert series.total() == pytest.approx(-750.0)+++def test_total_excludes_nav_marks_by_default():+ series = CashFlowSeries(+ flows=(+ _flow(1, -1000.0, kind="capital_call"),+ _flow(2, 250.0, kind="distribution"),+ _flow(3, 900.0, kind="nav"),+ )+ )+ assert series.total() == pytest.approx(-750.0)+ assert series.total(include_valuations=True) == pytest.approx(150.0)+++def test_nav_flow_is_flagged_as_a_valuation():+ assert _flow(1, 900.0, kind="nav").is_valuation+ assert not _flow(1, 900.0, kind="distribution").is_valuation+++# ---------------------------------------------------------------------------+# Empty series behaves sanely+# ---------------------------------------------------------------------------+++def test_empty_series_is_sane():+ series = CashFlowSeries()+ assert len(series) == 0+ assert series.is_empty+ assert series.dates() == ()+ assert series.amounts() == ()+ assert series.kinds() == ()+ assert series.total() == 0.0+ assert series.total(include_valuations=True) == 0.0+ assert list(series) == []+ assert series.currency is None+ assert series.filter(kind="coupon").is_empty+ assert series.between("2024-01-01", "2024-12-31").is_empty+++def test_empty_series_mean_style_arithmetic_does_not_divide_by_zero():+ """Guard the obvious downstream footgun: total over an empty series."""+ series = CashFlowSeries()+ count = len(series)+ average = series.total() / count if count else 0.0+ assert average == 0.0+++# ---------------------------------------------------------------------------+# Ingestion+# ---------------------------------------------------------------------------+++def test_load_cashflows_reads_a_fixture_csv(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ "date,amount,kind,currency\n"+ "2024-03-31,-1000.00,capital_call,USD\n"+ "2024-01-15,-500.00,capital_call,USD\n"+ "2024-06-30,250.00,distribution,USD\n",+ )+ series = load_cashflows(path)+ assert len(series) == 3+ assert series.currency == "USD"+ assert series.dates() == (date(2024, 1, 15), date(2024, 3, 31), date(2024, 6, 30))+ assert series.total() == pytest.approx(-1250.0)+ assert series.filter(kind="distribution").total() == pytest.approx(250.0)+++def test_load_cashflows_preserves_unmapped_columns_as_metadata(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ "date,amount,kind,currency,notice_id,fund\n"+ "2024-03-31,-1000.00,capital_call,USD,NOT-17,Fund II\n",+ )+ series = load_cashflows(path)+ flow = series[0]+ assert flow.metadata["notice_id"] == "NOT-17"+ assert flow.metadata["fund"] == "Fund II"+ assert flow.metadata["source_row"] == 1+ assert flow.metadata["source_file"] == str(path)+++def test_load_cashflows_missing_required_column_raises_not_none(tmp_path):+ path = _write_csv(+ tmp_path, "flows.csv", "date,kind,currency\n2024-03-31,coupon,USD\n"+ )+ with pytest.raises(CashFlowIngestError) as excinfo:+ load_cashflows(path)+ message = str(excinfo.value)+ assert "amount" in message+ assert "date, kind, currency" in message # tells the user what it did see+++def test_load_cashflows_missing_currency_is_an_error_not_a_default(tmp_path):+ path = _write_csv(tmp_path, "flows.csv", "date,amount,kind\n2024-03-31,10,coupon\n")+ with pytest.raises(CashFlowIngestError, match="currency"):+ load_cashflows(path)+++def test_load_cashflows_currency_argument_substitutes_for_a_missing_column(tmp_path):+ path = _write_csv(tmp_path, "flows.csv", "date,amount,kind\n2024-03-31,10,coupon\n")+ series = load_cashflows(path, currency="EUR")+ assert series.currency == "EUR"+ assert series[0].currency == "EUR"+++def test_load_cashflows_missing_kind_is_an_error_unless_defaulted(tmp_path):+ path = _write_csv(tmp_path, "flows.csv", "date,amount,currency\n2024-03-31,10,USD\n")+ with pytest.raises(CashFlowIngestError, match="default_kind"):+ load_cashflows(path)+ series = load_cashflows(path, default_kind="coupon")+ assert series[0].kind == "coupon"+++def test_load_cashflows_explicit_column_mapping(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ "Payment Date,Net Cash,Description\n2024-03-31,-1000,Drawdown 4\n",+ )+ series = load_cashflows(+ path,+ columns={"date": "Payment Date", "amount": "Net Cash"},+ currency="USD",+ default_kind="capital_call",+ )+ assert series[0].amount == -1000.0+ assert series[0].metadata["Description"] == "Drawdown 4"+++def test_load_cashflows_rejects_a_mapping_to_an_absent_column(tmp_path):+ path = _write_csv(tmp_path, "flows.csv", "date,amount,currency\n2024-03-31,10,USD\n")+ with pytest.raises(CashFlowIngestError, match="not in the file"):+ load_cashflows(path, columns={"amount": "Nope"}, default_kind="coupon")+++def test_load_cashflows_header_aliases_are_matched_case_insensitively(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ "Value Date,Cash Flow,Type,CCY\n2024-03-31,-1000,Capital Call,usd\n",+ )+ series = load_cashflows(path)+ assert series[0].kind == "capital_call"+ assert series[0].currency == "USD"+++def test_load_cashflows_parses_accounting_negatives_and_separators(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ 'date,amount,kind,currency\n2024-03-31,"(1,234.50)",capital_call,USD\n',+ )+ series = load_cashflows(path)+ assert series[0].amount == pytest.approx(-1234.50)+++def test_load_cashflows_reads_european_grouping_without_mangling_it(tmp_path):+ """1.234,50 must be 1234.50, not 1.2345."""+ path = _write_csv(+ tmp_path,+ "flows.csv",+ 'date,amount,kind,currency\n2024-03-31,"1.234,50",coupon,USD\n',+ )+ assert load_cashflows(path)[0].amount == pytest.approx(1234.50)+++def test_load_cashflows_refuses_an_ambiguous_single_comma(tmp_path):+ """'1,234' is 1234 in a US export and 1.234 in a European one."""+ path = _write_csv(+ tmp_path, "flows.csv", 'date,amount,kind,currency\n2024-03-31,"1,234",coupon,USD\n'+ )+ with pytest.raises(CashFlowIngestError, match="decimal_separator"):+ load_cashflows(path)+ assert load_cashflows(path, decimal_separator=".")[0].amount == pytest.approx(1234.0)+ assert load_cashflows(path, decimal_separator=",")[0].amount == pytest.approx(1.234)+++def test_load_cashflows_rejects_an_invalid_decimal_separator(tmp_path):+ path = _write_csv(+ tmp_path, "flows.csv", "date,amount,kind,currency\n2024-03-31,10,coupon,USD\n"+ )+ with pytest.raises(ValueError, match="decimal_separator must be"):+ load_cashflows(path, decimal_separator=";")+++def test_load_cashflows_strips_currency_symbols_and_nbsp(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ 'date,amount,kind,currency\n2024-03-31,"$ 1 234.50",coupon,USD\n',+ )+ assert load_cashflows(path)[0].amount == pytest.approx(1234.50)+++def test_load_cashflows_invert_sign_restores_the_convention(tmp_path):+ """A file reporting calls as positive is corrected at the boundary."""+ path = _write_csv(+ tmp_path, "flows.csv", "date,amount,kind,currency\n2024-03-31,1000,capital_call,USD\n"+ )+ with pytest.raises(CashFlowIngestError, match="negative"):+ load_cashflows(path)+ series = load_cashflows(path, invert_sign=True)+ assert series[0].amount == -1000.0+++def test_load_cashflows_requires_explicit_format_for_non_iso_dates(tmp_path):+ path = _write_csv(+ tmp_path, "flows.csv", "date,amount,kind,currency\n31/03/2024,10,coupon,USD\n"+ )+ with pytest.raises(CashFlowIngestError, match="date_format"):+ load_cashflows(path)+ series = load_cashflows(path, date_format="%d/%m/%Y")+ assert series[0].date == date(2024, 3, 31)+++def test_load_cashflows_blank_amount_is_an_error_not_zero(tmp_path):+ path = _write_csv(+ tmp_path, "flows.csv", "date,amount,kind,currency\n2024-03-31,,coupon,USD\n"+ )+ with pytest.raises(CashFlowIngestError, match="blank"):+ load_cashflows(path)+++def test_load_cashflows_reports_the_offending_row_number(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ "date,amount,kind,currency\n"+ "2024-01-31,10,coupon,USD\n"+ "2024-02-29,oops,coupon,USD\n",+ )+ with pytest.raises(CashFlowIngestError, match="row 2"):+ load_cashflows(path)+++def test_load_cashflows_missing_file_raises_ingest_error(tmp_path):+ with pytest.raises(CashFlowIngestError, match="not found"):+ load_cashflows(tmp_path / "absent.csv")+++def test_load_cashflows_unsupported_suffix_is_explicit(tmp_path):+ path = _write_csv(tmp_path, "flows.xlsx", "date,amount\n")+ with pytest.raises(CashFlowIngestError, match="unsupported file type"):+ load_cashflows(path, currency="USD", default_kind="coupon")+++def test_load_cashflows_header_only_file_yields_an_empty_series(tmp_path):+ path = _write_csv(tmp_path, "flows.csv", "date,amount,kind,currency\n")+ series = load_cashflows(path, currency="USD")+ assert series.is_empty+ assert series.total() == 0.0+++def test_load_cashflows_mixed_currency_file_is_refused(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ "date,amount,kind,currency\n"+ "2024-03-31,100,coupon,USD\n"+ "2024-04-30,100,coupon,EUR\n",+ )+ with pytest.raises(CurrencyMismatchError):+ load_cashflows(path)+++def test_load_cashflows_tsv_delimiter_inferred_from_suffix(tmp_path):+ path = _write_csv(+ tmp_path, "flows.tsv", "date\tamount\tkind\tcurrency\n2024-03-31\t10\tcoupon\tUSD\n"+ )+ series = load_cashflows(path)+ assert series[0].amount == 10.0+++def test_load_cashflows_skips_trailing_blank_line(tmp_path):+ path = _write_csv(+ tmp_path,+ "flows.csv",+ "date,amount,kind,currency\n2024-03-31,10,coupon,USD\n,,,\n",+ )+ assert len(load_cashflows(path)) == 1+++# ---------------------------------------------------------------------------+# Entity / instrument models+# ---------------------------------------------------------------------------+++def test_entity_constructs_and_is_immutable():+ entity = Entity(entity_id="LEI-123", name="Acme Capital", entity_type="manager")+ assert entity.entity_type is EntityType.MANAGER+ with pytest.raises(dataclasses.FrozenInstanceError):+ entity.name = "Other"+++def test_entity_rejects_blank_id_and_unknown_type():+ with pytest.raises(ValueError, match="entity_id is required"):+ Entity(entity_id=" ")+ with pytest.raises(ValueError, match="unknown entity_type"):+ Entity(entity_id="E1", entity_type="wizard")+++def test_entity_cannot_be_its_own_parent():+ with pytest.raises(ValueError, match="own parent"):+ Entity(entity_id="E1", parent_id="E1")+++def test_instrument_requires_currency_and_normalizes_it():+ instrument = Instrument(instrument_id="X1", currency="usd")+ assert instrument.currency == "USD"+ with pytest.raises(ValueError, match="currency is required"):+ Instrument(instrument_id="X1", currency="")+++def test_instrument_accepts_a_crypto_quote_asset():+ """Currency is not constrained to three letters; USDT is real here."""+ assert Instrument(instrument_id="BTC-USDT", currency="USDT").currency == "USDT"+++def test_security_carries_venue_details():+ issuer = Entity(entity_id="CIK-320193", name="Apple Inc.")+ security = Security(+ instrument_id="US0378331005",+ currency="USD",+ symbol="AAPL",+ exchange="XNAS",+ security_type="etf",+ issuer=issuer,+ )+ assert security.security_type is SecurityType.ETF+ assert security.issuer.name == "Apple Inc."+ assert isinstance(security, Instrument)+++def test_fund_validates_its_economics():+ fund = Fund(+ instrument_id="FUND-II",+ currency="EUR",+ vintage_year=2021,+ structure="closed_end",+ commitment=25_000_000,+ management_fee_rate=0.02,+ )+ assert fund.structure is FundStructure.CLOSED_END+ assert fund.commitment == 25_000_000.0+ with pytest.raises(ValueError, match="non-negative"):+ Fund(instrument_id="F", currency="EUR", commitment=-1)+ with pytest.raises(ValueError, match="decimal fraction"):+ Fund(instrument_id="F", currency="EUR", management_fee_rate=2.0)+ with pytest.raises(ValueError, match="vintage_year"):+ Fund(instrument_id="F", currency="EUR", vintage_year=12)+++def test_bond_validates_coupon_and_maturity():+ bond = Bond(+ instrument_id="US912828",+ currency="USD",+ face_value=1000,+ coupon_rate=0.045,+ coupon_frequency=2,+ inception_date="2020-01-15",+ maturity_date="2030-01-15",+ )+ assert bond.maturity_date == date(2030, 1, 15)+ assert bond.coupon_rate == pytest.approx(0.045)++ with pytest.raises(ValueError, match="percentage"):+ Bond(instrument_id="B", currency="USD", coupon_rate=4.5)+ with pytest.raises(ValueError, match="face_value must be positive"):+ Bond(instrument_id="B", currency="USD", face_value=0)+ with pytest.raises(ValueError, match="zero-coupon"):+ Bond(instrument_id="B", currency="USD", coupon_rate=0.05, coupon_frequency=0)+ with pytest.raises(ValueError, match="precedes inception"):+ Bond(+ instrument_id="B",+ currency="USD",+ inception_date="2030-01-01",+ maturity_date="2020-01-01",+ )+++def test_zero_coupon_bond_is_valid():+ bond = Bond(instrument_id="Z", currency="USD", coupon_rate=0.0, coupon_frequency=0)+ assert bond.coupon_frequency == 0+++# ---------------------------------------------------------------------------+# The parallel-path guarantee+# ---------------------------------------------------------------------------+++def test_spine_does_not_widen_the_bar_price_panel():+ """A nav must never become a column a bar engine could price as a close."""+ from backtest.runner import _PRICE_PANEL_COLUMNS, _VALID_INTERVALS++ assert _PRICE_PANEL_COLUMNS == ("open", "high", "low", "close", "volume", "vwap", "amount")+ assert "nav" not in _PRICE_PANEL_COLUMNS+ assert _VALID_INTERVALS == {"1m", "5m", "15m", "30m", "1H", "4H", "1D"}+++def test_series_is_not_a_dataframe_and_exposes_no_bar_fields():+ series = CashFlowSeries(flows=(_flow(1, 100.0, kind="nav"),))+ assert not hasattr(series, "close")+ assert not hasattr(series[0], "close")