Skip to content

"Vibe-Trading: Your Personal Trading Agent"

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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 source
diff --git a/agent/tests/test_entities_spine.py b/agent/tests/test_entities_spine.py
new file mode 100644
index 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")