portlearn 0.0.1.dev0__py3-none-any.whl

portlearn/observations.py

@@ -0,0 +1,288 @@
+"""Point-in-time observations, vintages, and feature lineage.
+
+This module freezes the information semantics:
+
+- **Data law** — data is what observations exist: records carrying both
+  ``observation_time`` (when the underlying phenomenon is dated) and
+  ``available_time`` (when the information first could have been known);
+  an observation without declared availability is not data PortLearn can
+  admit.
+- **Identity law** — an observation's identity is the triple
+  ``(series_id, observation_time, available_time)``.  A revision is a
+  separate record with the same ``series_id`` and ``observation_time``
+  and a later ``available_time``; revisions are never mutations.
+  ``series_id`` is an opaque, non-empty, non-blank string compared by
+  exact string equality — no case folding, whitespace stripping, or
+  Unicode normalization of any kind.
+- **Vintage law** — at a decision time, the visible vintage of a
+  series-observation is the record with the latest ``available_time``
+  at or before the decision; a revised value is invisible before its
+  own availability.  ``vintage_as_of`` accepts exactly one
+  ``(series_id, observation_time)`` group and rejects duplicate
+  full-identity records and mixed-group input fail-closed.
+- **Feature lineage law** — a derived feature may not be declared
+  available before its latest input: ``feature available_time ≥
+  max(input available_times)``, and an empty input collection has no
+  defensible availability.
+
+This module owns ``AmbiguousObservationError`` and
+``FeatureLineageError`` and imports the timing errors it raises;
+``portlearn.timing`` imports nothing from here, so no
+import cycle exists on this contract surface.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from .timing import (
+    InvalidChronologyError,
+    MissingAvailabilityError,
+    NaiveTimestampError,  # noqa: F401  # re-exported: raised at this surface by the validator from portlearn.timing
+    _require_aware_instant,  # noqa: F401  # re-exported: the shared validator from portlearn.timing, imported per the reuse law
+    instant_key,
+    to_instant,
+)
+
+__all__ = [
+    "AmbiguousObservationError",
+    "FeatureLineageError",
+    "TimedObservation",
+    "require_lineage_monotone",
+    "vintage_as_of",
+]
+
+
+# --------------------------------------------------------------------------- #
+# Fail-closed error taxonomy — the observations-owned arm
+# --------------------------------------------------------------------------- #
+
+
+class AmbiguousObservationError(Exception):
+    """Observation identity is ambiguous: duplicate records or mixed input.
+
+    Raised when two records share the full identity triple
+    ``(series_id, observation_time, available_time)`` — whether or not
+    their values agree, since the identity triple is a key with no
+    last-write-wins and no value-equality exception — or when input to
+    ``vintage_as_of`` spans more than one ``(series_id,
+    observation_time)`` group.  No preference rule is applied.
+    """
+
+
+class FeatureLineageError(Exception):
+    """A feature's declared availability violates lineage monotonicity.
+
+    A derived feature may not be declared available before its latest
+    input's availability, and a feature with an empty input collection
+    has no defensible availability at all: both fail closed rather than
+    warn, because a feature visible before the data it derives from is
+    look-ahead leakage.
+    """
+
+
+# --------------------------------------------------------------------------- #
+# Instant validation — reused, not re-implemented
+# --------------------------------------------------------------------------- #
+
+# The aware-instant validator is implemented in ``portlearn.timing``
+# and imported above: shared invariant validation has exactly one
+# implementation, and every surface that needs it re-exports that
+# exact function object by import, so re-exports preserve object
+# identity package-wide.  The canonical invalid-input wording —
+# including its calendar-date tail — is timing.py's.
+
+
+# --------------------------------------------------------------------------- #
+# The observation value object
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class TimedObservation:
+    """One point-in-time record of a series observation.
+
+    ``observation_time`` is when the underlying phenomenon is dated;
+    ``available_time`` is when the information first could have been
+    known (publication is one source of availability); ``value`` is the
+    observed figure.  The identity of the record is the triple
+    ``(series_id, observation_time, available_time)``: a revision is a
+    separate record with a later ``available_time``, never a mutation.
+
+    Construction is fail-closed: ``series_id`` must be a non-empty,
+    non-blank string (validated with the built-in ``ValueError`` because
+    a blank identifier names no series); both instants must be aware;
+    ``available_time`` may not be absent, ``None``, or precede the
+    observation it describes.  The identifier is preserved exactly —
+    no case folding, trimming, or Unicode normalization.
+    """
+
+    series_id: str
+    observation_time: datetime
+    available_time: datetime
+    value: Any
+
+    def __post_init__(self) -> None:
+        # ValueError (not TypeError) is pinned for non-string identifiers:
+        # the built-in ValueError is the closed-taxonomy choice for every
+        # malformed series_id, non-string included.
+        if not isinstance(self.series_id, str):
+            raise ValueError(  # noqa: TRY004 — pinned for malformed identifiers
+                "series_id must be a string identifier naming the series "
+                "the observation belongs to; got "
+                f"{type(self.series_id).__name__}: {self.series_id!r}. "
+                "A non-string identifier names no series, so the "
+                "observation is rejected fail-closed."
+            )
+        if not self.series_id.strip():
+            raise ValueError(
+                "series_id must be a non-empty, non-blank string identifier "
+                f"naming the series the observation belongs to; got "
+                f"{self.series_id!r}. A blank identifier names no series, "
+                "so the observation is rejected fail-closed."
+            )
+        observation = to_instant(
+            self.observation_time, "observation_time"
+        )
+        if self.available_time is None:
+            raise MissingAvailabilityError(
+                f"the observation for series {self.series_id!r} declares "
+                "available_time=None; availability is mandatory — a source "
+                "unable to declare when the information first could have "
+                "been known must fail, never default"
+            )
+        available = to_instant(self.available_time, "available_time")
+        if available < observation:
+            raise InvalidChronologyError(
+                "chronology violation: availability may not precede the "
+                f"observation it describes, but series {self.series_id!r} "
+                f"declares observation_time={observation.isoformat()} after "
+                f"available_time={available.isoformat()}. Information "
+                "cannot be published before the phenomenon it reports."
+            )
+
+
+# --------------------------------------------------------------------------- #
+# Point-in-time vintage selection
+# --------------------------------------------------------------------------- #
+
+
+def vintage_as_of(
+    observations: Sequence[TimedObservation], decision_time: Any
+) -> TimedObservation | None:
+    """The visible vintage of one series-observation at a decision time.
+
+    Selection follows the point-in-time rule: among
+    exactly one ``(series_id, observation_time)`` group, the visible
+    vintage is the record with the latest ``available_time`` at or
+    before ``decision_time`` — availability exactly at the decision is
+    visible.  A revised value is invisible before its own availability.
+
+    Evaluation is fail-closed in this order: ``decision_time`` is
+    validated as an aware instant before
+    any branching; empty input returns ``None`` (no vintage, explicitly
+    not an error); input spanning more than one group rejects with
+    ``AmbiguousObservationError``; duplicate full-identity records
+    reject with ``AmbiguousObservationError`` whether or not their
+    values agree; when no record is visible, the outcome is ``None``,
+    again not an error.
+    """
+    decision = to_instant(decision_time, "decision_time")
+
+    if not observations:
+        return None
+
+    groups: dict[tuple[str, datetime], list[TimedObservation]] = {}
+    for record in observations:
+        groups.setdefault(
+            (record.series_id, instant_key(record.observation_time)), []
+        ).append(record)
+
+    if len(groups) > 1:
+        named = sorted({series_id for series_id, _ in groups})
+        raise AmbiguousObservationError(
+            "ambiguous observation input: the records span more than one "
+            f"(series_id, observation_time) group — series {named!r} — so "
+            "no single series-observation vintage can be selected without "
+            "an illegitimate cross-group preference rule. Submit exactly "
+            "one group per vintage query."
+        )
+
+    group = next(iter(groups.values()))
+    seen: set[tuple[str, datetime, datetime]] = set()
+    for record in group:
+        identity = (
+            record.series_id,
+            instant_key(record.observation_time),
+            instant_key(record.available_time),
+        )
+        if identity in seen:
+            raise AmbiguousObservationError(
+                "ambiguous observation input: two records share the full "
+                f"identity triple (series_id={record.series_id!r}, "
+                f"observation_time={record.observation_time.isoformat()}, "
+                f"available_time={record.available_time.isoformat()}) — the "
+                "identity triple is a key, so there is no last-write-wins "
+                "and no value-equality exception; conflicting or "
+                "indeterminate availability fails closed."
+            )
+        seen.add(identity)
+
+    visible = [
+        record
+        for record in group
+        if instant_key(record.available_time) <= decision
+    ]
+    if not visible:
+        return None
+    return max(visible, key=lambda record: instant_key(record.available_time))
+
+
+# --------------------------------------------------------------------------- #
+# Feature lineage monotonicity
+# --------------------------------------------------------------------------- #
+
+
+def require_lineage_monotone(
+    feature_available_time: Any, input_available_times: Iterable[Any]
+) -> None:
+    """Assert a feature is not declared available before its latest input.
+
+    A derived feature may enter an information set no earlier than the
+    latest input it derives from: ``feature_available_time`` must be at
+    or after ``max(input_available_times)``.  An
+    empty input collection also rejects — a feature with no declared
+    inputs has no defensible availability.  Both the feature instant
+    and every input instant must be aware; naive or date inputs fail
+    closed with ``NaiveTimestampError`` on this surface too.
+    """
+    feature_available = to_instant(
+        feature_available_time, "feature_available_time"
+    )
+
+    inputs = list(input_available_times)
+    if not inputs:
+        raise FeatureLineageError(
+            "feature lineage violation: the feature declares an empty "
+            "input collection, so no input availability bounds its own — "
+            "a feature with no declared inputs has no defensible "
+            "availability and cannot be admitted."
+        )
+
+    input_instants = [
+        to_instant(instant, "input_available_time") for instant in inputs
+    ]
+    latest_input = max(input_instants)
+
+    if feature_available < latest_input:
+        raise FeatureLineageError(
+            "feature lineage violation: the feature is declared available "
+            "before its latest input — feature_available_time="
+            f"{feature_available.isoformat()} precedes the latest "
+            f"input_available_time={latest_input.isoformat()}. A derived "
+            "value visible before the data it derives from is look-ahead "
+            "leakage, so the declaration is rejected."
+        )

portlearn/timing.py

@@ -0,0 +1,328 @@
+"""Time-index and admission contracts for portfolio decisions.
+
+This module freezes the timing semantics:
+
+- every financial time is a timezone-aware instant, compared as instants
+  (wall clock and zone name never affect ordering or equality);
+- naive datetimes and ``datetime.date`` inputs are rejected fail-closed —
+  no default zone is ever assumed and no date-to-midnight coercion is
+  ever performed, because silent coercion is the classic daily-data
+  look-ahead leakage vector;
+- the chronology law
+
+  ``observation_time ≤ available_time ≤ decision_time ≤ execution_time
+  ≤ realization start_time < realization end_time``
+
+  holds with equal adjacent instants admissible at every ``≤`` boundary
+  (zero publication lag, availability exactly at the decision,
+  same-instant decide-and-execute) and strictly positive realization
+  length;
+- the admission law: an item of information may enter the information
+  set for a decision at ``decision_time`` iff its ``available_time`` is
+  at or before ``decision_time``, evaluated on aware instants.  The gate
+  is the decision instant only, never the execution instant, so
+  information arriving in the decision-to-execution gap is look-ahead
+  leakage and is rejected.
+
+This module defines four fail-closed errors:
+``NaiveTimestampError``, ``InvalidChronologyError``,
+``FutureInformationError``, and ``MissingAvailabilityError``.  It is
+stdlib-only and imports nothing from ``portlearn.observations``, so no
+import cycle exists on the frozen contract surface.  Every semantic
+ordering, equality, and identity-key comparison operates on the
+normalized UTC instant (``to_instant`` / ``instant_key``), so DST-fold
+ambiguity can never make two distinct instants compare equal.
+PortLearn renders instants in no local timezone of its own;
+formatting an instant for display in any zone is the caller's
+concern, and no contract comparison depends on any local timezone.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, date, datetime
+from typing import Any
+
+__all__ = [
+    "DecisionTiming",
+    "FutureInformationError",
+    "InvalidChronologyError",
+    "MissingAvailabilityError",
+    "NaiveTimestampError",
+    "ReturnRealizationPeriod",
+    "instant_key",
+    "is_available_for_decision",
+    "require_available_for_decision",
+    "to_instant",
+]
+
+
+# --------------------------------------------------------------------------- #
+# Fail-closed error taxonomy — the timing-owned arm
+# --------------------------------------------------------------------------- #
+
+
+class NaiveTimestampError(Exception):
+    """A time input lacks an explicit timezone, or a date was supplied.
+
+    Financial times are compared as instants on a single timeline.  An
+    instant without an explicit UTC offset cannot be placed on that
+    timeline without assuming a default zone, and a ``datetime.date``
+    cannot be placed on it without silently coercing it to that date's
+    midnight — the classic daily-data leakage vector.  PortLearn does
+    neither, so the input is rejected.
+    """
+
+
+class InvalidChronologyError(Exception):
+    """The chronology law was violated.
+
+    Availability may not precede the observation it describes, a trade
+    may not execute before its decision is made, outcomes may not start
+    realizing before the trade executes, and the return-realization
+    period must have strictly positive length.
+    """
+
+
+class FutureInformationError(Exception):
+    """An item failing the admission law was submitted for a decision.
+
+    This is the look-ahead rejection: the item's ``available_time`` is
+    after the ``decision_time`` of the decision that would consume it,
+    so admitting it would let the decision see information that did not
+    exist yet.
+    """
+
+
+class MissingAvailabilityError(Exception):
+    """``available_time`` is absent or ``None`` on a submitted item.
+
+    Availability is mandatory: a source unable to declare when the
+    information first could have been known must fail, never default to
+    the observation instant, "immediately available", or "never
+    available".
+    """
+
+
+# --------------------------------------------------------------------------- #
+# Instant validation
+# --------------------------------------------------------------------------- #
+
+
+def _require_aware_instant(value: Any, field_name: str) -> datetime:
+    """Return ``value`` as a timezone-aware instant, or fail closed.
+
+    Naive datetimes, ``datetime.date`` inputs, and non-instant inputs
+    are all rejected with ``NaiveTimestampError``: no default timezone
+    is assumed and no date-to-midnight coercion is performed anywhere.
+    """
+    if isinstance(value, datetime):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise NaiveTimestampError(
+                f"{field_name} is a naive timestamp — it carries no explicit "
+                f"UTC offset, so it cannot be placed on the single timeline "
+                f"on which financial times are compared without assuming a "
+                f"default timezone; got {value!r}. Supply a timezone-aware "
+                "datetime (an explicit offset) instead."
+            )
+        return value
+    if isinstance(value, date):
+        raise NaiveTimestampError(
+            f"{field_name} is a calendar date ({value.isoformat()}), not an "
+            "instant: PortLearn never coerces a date to that date's "
+            "midnight, because such coercion is the classic daily-data "
+            "look-ahead leakage vector. Supply a timezone-aware datetime "
+            "with an explicit UTC offset declaring when the information "
+            "first could have been known."
+        )
+    raise NaiveTimestampError(
+        f"{field_name} must be a timezone-aware datetime instant carrying "
+        f"an explicit UTC offset; got {type(value).__name__}: {value!r}. "
+        "Financial times are compared as instants, so an input that is not "
+        "an aware instant is rejected fail-closed."
+    )
+
+
+def _item_available_time(item: Any) -> datetime:
+    """Extract and validate ``item.available_time`` for the admission law.
+
+    Attribute absence and ``None`` are ``MissingAvailabilityError``; a
+    naive datetime or a ``datetime.date`` is ``NaiveTimestampError``.
+    """
+    try:
+        available = item.available_time
+    except AttributeError:
+        raise MissingAvailabilityError(
+            "the submitted information item declares no available_time; "
+            "availability is mandatory on every contract surface — a source "
+            "unable to declare when the information first could have been "
+            "known must fail, never default"
+        ) from None
+    if available is None:
+        raise MissingAvailabilityError(
+            "the submitted information item declares available_time=None; "
+            "availability is mandatory on every contract surface — a source "
+            "unable to declare when the information first could have been "
+            "known must fail, never default"
+        )
+    return _require_aware_instant(available, "available_time")
+
+
+def _item_series_id(item: Any) -> Any:
+    """The item's series identifier when one is in context."""
+    return getattr(item, "series_id", None)
+
+
+# --------------------------------------------------------------------------- #
+# Instant normalization — the single comparison basis
+# --------------------------------------------------------------------------- #
+
+
+def to_instant(value: Any, field_name: str = "timestamp") -> datetime:
+    """Return the UTC datetime denoting ``value``'s true instant.
+
+    ``value`` is validated fail-closed exactly as
+    ``_require_aware_instant`` validates it, then normalized through
+    ``astimezone(timezone.utc)``, which resolves ``fold`` through the
+    zone's ``utcoffset``: the two Melbourne 2026-04-05 02:30
+    ambiguities normalize to ``2026-04-04T15:30Z`` (fold=0, UTC+11)
+    and ``2026-04-04T16:30Z`` (fold=1, UTC+10).  Every semantic
+    ordering and equality comparison in this package compares these
+    normalized instants, never the raw datetimes, because raw
+    aware-datetime comparison ignores ``fold`` whenever both sides
+    share one ``tzinfo`` object and can therefore call two distinct
+    instants equal.  Original datetime objects stay stored where
+    they are held for provenance and display; normalization serves
+    comparison only — stored data is never UTC-converted.
+    """
+    moment = _require_aware_instant(value, field_name)
+    return moment.astimezone(UTC)
+
+
+def instant_key(value: Any, field_name: str = "timestamp") -> datetime:
+    """Hashable normalized-UTC identity for timestamp keys and sorting.
+
+    The same normalization as ``to_instant``, named for its role:
+    use it wherever a datetime becomes a dictionary key, a set
+    member, or a sort key, so two fold-distinct instants never
+    silently merge into one identity.  Sorting on ``instant_key``
+    values is safe because they all carry ``timezone.utc``, where no
+    fold ambiguity exists.
+    """
+    return to_instant(value, field_name)
+
+
+# --------------------------------------------------------------------------- #
+# Value objects
+# --------------------------------------------------------------------------- #
+
+
+@dataclass(frozen=True)
+class ReturnRealizationPeriod:
+    """The half-open instant interval ``[start_time, end_time)`` over
+    which a decision's outcome realizes.
+
+    Both bounds must be aware instants and the period must have strictly
+    positive length: ``start_time < end_time``.  Equal adjacent bounds
+    are admissible everywhere else in the chronology law, but a
+    zero-length or reversed realization period is malformed.
+    """
+
+    start_time: datetime
+    end_time: datetime
+
+    def __post_init__(self) -> None:
+        start = to_instant(self.start_time, "realization start_time")
+        end = to_instant(self.end_time, "realization end_time")
+        if not start < end:
+            raise InvalidChronologyError(
+                "malformed return-realization period: start_time must "
+                "strictly precede end_time so the half-open period "
+                f"[start_time, end_time) has strictly positive length; got "
+                f"start_time={start.isoformat()}, end_time={end.isoformat()}"
+            )
+
+
+@dataclass(frozen=True)
+class DecisionTiming:
+    """When a single portfolio decision is made, executed, and realized.
+
+    Validates the decision-event portion of the chronology law:
+    ``decision_time ≤ execution_time ≤ realization start_time``,
+    with equal adjacent instants admissible (same-instant
+    decide-and-execute is an explicit design) and all instants aware.
+    Rebalance schedules and decision frequency are out of scope here.
+    """
+
+    decision_time: datetime
+    execution_time: datetime
+    return_realization_period: ReturnRealizationPeriod
+
+    def __post_init__(self) -> None:
+        decision = to_instant(self.decision_time, "decision_time")
+        execution = to_instant(self.execution_time, "execution_time")
+        start = to_instant(
+            self.return_realization_period.start_time, "realization start_time"
+        )
+        if execution < decision:
+            raise InvalidChronologyError(
+                "chronology violation: a trade cannot execute before its "
+                "decision is made, but execution_time precedes "
+                f"decision_time; got decision_time={decision.isoformat()}, "
+                f"execution_time={execution.isoformat()}"
+            )
+        if start < execution:
+            raise InvalidChronologyError(
+                "chronology violation: outcomes cannot start realizing "
+                "before the trade executes, but realization start_time "
+                "precedes execution_time; got execution_time="
+                f"{execution.isoformat()}, realization start_time="
+                f"{start.isoformat()}"
+            )
+
+
+# --------------------------------------------------------------------------- #
+# The admission law
+# --------------------------------------------------------------------------- #
+
+
+def is_available_for_decision(item: Any, decision_time: Any) -> bool:
+    """Pure admission query: is ``item``'s information visible yet?
+
+    Returns ``True`` iff ``item.available_time <= decision_time`` on
+    aware instants — availability exactly at the decision admits the
+    item.  ``False`` means "not yet available", a legitimate verdict,
+    never a silent drop.  Malformed inputs still raise: the
+    ``decision_time`` is validated before any comparison, and an item
+    whose ``available_time`` is absent, ``None``, naive, or a date fails
+    closed with its typed error so "not yet available" is never
+    conflated with "malformed".
+    """
+    decision = to_instant(decision_time, "decision_time")
+    available = to_instant(_item_available_time(item), "available_time")
+    return available <= decision
+
+
+def require_available_for_decision(item: Any, decision_time: Any) -> None:
+    """Admission gate: raise on look-ahead, return ``None`` on admission.
+
+    Raises ``FutureInformationError`` when ``item.available_time`` is
+    after ``decision_time`` — including information arriving inside the
+    decision-to-execution gap, which satisfies no admission verdict
+    because the gate is the decision instant only, never the execution
+    instant.  Malformed inputs raise their typed
+    errors exactly as the boolean query does.
+    """
+    decision = to_instant(decision_time, "decision_time")
+    available = to_instant(_item_available_time(item), "available_time")
+    if available > decision:
+        series_id = _item_series_id(item)
+        raise FutureInformationError(
+            f"look-ahead rejection: the information item {series_id!r} is "
+            "not available at the decision instant — available_time="
+            f"{available.isoformat()} is after decision_time="
+            f"{decision.isoformat()}. Information that first could have "
+            "been known after the decision (including inside the "
+            "decision-to-execution gap) is future information and may not "
+            "enter the information set."
+        )

portlearn-0.0.1.dev0.dist-info/METADATA

@@ -0,0 +1,70 @@
+Metadata-Version: 2.5
+Name: portlearn
+Version: 0.0.1.dev0
+Summary: Finance-first research framework for controlled, reproducible, and modular experimentation in machine-learned portfolio choice.
+Project-URL: Repository, https://github.com/fmasoudy/PortLearn
+Project-URL: Issues, https://github.com/fmasoudy/PortLearn/issues
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# PortLearn
+
+PortLearn is a finance-first research framework for controlled, reproducible, and modular experimentation in machine-learned portfolio choice.
+
+> Change the research component without accidentally changing the financial experiment.
+
+PortLearn is being developed to support comparable portfolio-learning research across classical methods, forecasting-based machine learning, direct deep learning, reinforcement learning, optimization-based approaches, and user-defined research components under common financial experiment contracts.
+
+## Status
+
+PortLearn is in early development and has not yet been published as a stable package release. The current public surface exposes the research foundation and API contracts. The public API is not yet stable.
+
+## Design Direction
+
+PortLearn aims to provide reusable infrastructure for:
+
+- financial data and information-set construction;
+- modular feature engineering;
+- portfolio strategy composition;
+- common portfolio accounting;
+- controlled comparison of alternative methods;
+- research reproducibility and provenance.
+
+PortLearn is a research toolkit, not a repository for individual paper-specific models or unpublished research architectures.
+
+## Roadmap
+
+PortLearn is under active research development. This roadmap is intentionally high-level: it communicates broad direction only, is subject to change as the research framework develops, and does not promise dates or specific functionality.
+
+**Available now**
+
+- Research foundation: time/chronology contracts, observation handling, information sets, and the core research interfaces that define how portfolio research components compose.
+- Validation utilities for detecting violations of point-in-time information contracts.
+- Canonical run manifests for recording environment and command provenance.
+
+**Next**
+
+- Datasets and data access: adapters and alignment for market and macro data.
+- Experiment and reproducibility infrastructure.
+
+**Planned**
+
+- Forecasting methods.
+- Portfolio construction and accounting.
+- Later deep-learning and reinforcement-learning research capabilities.
+
+Entries move forward on this roadmap as the underlying research foundation stabilizes; nothing here is a dated commitment.
+
+## Development
+
+The local development battery, from a fresh clone:
+
+```console
+uv sync --locked
+uv run ruff check .
+uv run pytest
+uv build
+uv run python scripts/verify_built_wheel.py
+```