portlearn 0.0.1.dev1__tar.gz → 0.0.1.dev3__tar.gz

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/.github/workflows/ci.yml

@@ -1,6 +1,6 @@
 # Public CI for PortLearn.
 # Runs on every push and pull request, guarded to the public fmasoudy/
-# PortLearn repository, least-privilege permissions, frozen
+# PortLearn repository, least-privilege permissions, fixed
 # per-interpreter sequence, single dependent build-and-verify-wheel job,
 # immutable action pins.
 name: ci
@@ -28,7 +28,7 @@ jobs:
         uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           version: "0.12.10"
-      - name: Run the frozen per-interpreter sequence
+      - name: Run the fixed per-interpreter sequence
         run: |
           uv sync --locked --python ${{ matrix.python-version }}
           uv run --python ${{ matrix.python-version }} ruff check .

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/.github/workflows/release.yml

@@ -8,7 +8,7 @@
 # It validates every consistency rule FIRST and fails closed on any
 # mismatch, leaving no partial state beyond the failed run log. It never
 # deletes, moves, or overwrites an existing tag or release. Existence
-# queries fail closed the same way: a query whose answer cannot be
+# queries unconditional the same way: a query whose answer cannot be
 # confirmed (transport error, auth error, unexpected HTTP status)
 # aborts the run rather than being read as "absent". Runs are also
 # serialized in a 'public-release' concurrency group (no cancel), so
@@ -77,7 +77,7 @@ jobs:
           # final release creation, which names its token and
           # repository explicitly.
           persist-credentials: false
-      - name: Fail closed unless the target commit is the current origin main head
+      - name: abort unless the target commit is the current origin main head
         run: |
           set -euo pipefail
           git fetch --no-tags origin "+refs/heads/main:refs/remotes/origin/main"
@@ -88,7 +88,7 @@ jobs:
             echo "::error::target ${PL_TARGET_SHA} is not the current origin/main head (${main_head}); a stale or off-main commit is never tagged"
             exit 1
           fi
-      - name: Fail closed if the tag already exists locally or on the remote
+      - name: Abort if the tag already exists locally or on the remote
         run: |
           set -euo pipefail
           if [ -n "$(git tag --list "$PL_TAG_NAME")" ]; then
@@ -109,7 +109,7 @@ jobs:
             echo "::error::remote tag ${PL_TAG_NAME} already exists; existing tags are never overwritten"
             exit 1
           fi
-      - name: Fail closed if the GitHub Release already exists
+      - name: Abort if the GitHub Release already exists
         env:
           GH_TOKEN: ${{ github.token }}
           GH_REPO: ${{ github.repository }}
@@ -358,7 +358,7 @@ jobs:
           def main(argv: list[str] | None = None) -> int:
               """Run validation from command-line arguments; 0 on success."""
               parser = argparse.ArgumentParser(
-                  description="Validate a public release request (fail-closed)."
+                  description="Validate a public release request (unconditional)."
               )
               parser.add_argument("--version", required=True)
               parser.add_argument("--tag-name", required=True)
@@ -404,7 +404,7 @@ jobs:
         run: |
           set -euo pipefail
           git tag --list "v*" | sort > "${RUNNER_TEMP}/existing_tags.txt"
-      - name: Fail closed on any release-consistency mismatch
+      - name: Abort on any release-consistency mismatch
         run: |
           set -euo pipefail
           uv sync --locked

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/.gitignore

@@ -16,5 +16,5 @@ venv/
 # OS
 .DS_Store
 
-# Local scratch (never commit run artifacts without an explicit milestone decision)
+# Local scratch (never commit run artifacts without an explicit release decision)
 scratch/

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/CHANGELOG.md

@@ -2,12 +2,37 @@
 
 All notable public changes to PortLearn are documented in this file.
 
-Git history remains the detailed development record. This changelog is the curated user/researcher-facing history: it tracks meaningful public changes and public software releases, with release sections recording releases and the entries within them recording user-visible changes.
-
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning follows the project's PEP 440 policy: early-development `0.0.x` public releases.
 
 ## [Unreleased]
 
+## [0.0.1.dev3]
+
+### Added
+
+- Strategies: the `portlearn.strategies` module with the four built-in classical strategies — `EqualWeight`, `InverseVolatility`, `MinimumVariance`, and `MeanVariance` — implementing the strategy decision contract.
+- SciPy ships as a core runtime dependency: the constrained optimization solvers used by `MinimumVariance` and `MeanVariance` are available from a plain `pip install portlearn`. SciPy is lazily imported inside the internal optimizer adapter, never at package import.
+
+## [0.0.1.dev2]
+
+### Added
+
+- Portfolio weights: the `portlearn.weights` module with the closed portfolio-role vocabulary, target-weight validation, and immutable weight books.
+- Rebalancing: schedule policies and the drift law carrying held weights across holding segments (`portlearn.rebalance`).
+- Transaction and turnover accounting with proportional transaction-cost models (`portlearn.trades`, `portlearn.turnover`, `portlearn.costs`).
+- The transaction ledger: segment-composed accounting over the wealth path with the reference accounting engine (`portlearn.ledger`).
+- The strategy decision-contract seam — `Strategy.decide(context) -> DecisionResult` over `DecisionContext`, validated by `require_decision_result_compatible`.
+- Lazy module facades for the portfolio modules under the top-level package namespace.
+- Public test modules covering the portfolio-weight, rebalance, transaction, cost, ledger, and decision-contract surfaces.
+
+### Changed
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
 ## [0.0.1.dev1]
 
 ### Added

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: portlearn
-Version: 0.0.1.dev1
+Version: 0.0.1.dev3
 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
@@ -8,6 +8,7 @@ License-Expression: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.11
 Requires-Dist: pandas>=2.2.3
+Requires-Dist: scipy>=1.14
 Provides-Extra: parquet
 Requires-Dist: pyarrow<26,>=21.0.0; extra == 'parquet'
 Provides-Extra: plot
@@ -16,8 +17,8 @@ Description-Content-Type: text/markdown
 
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
-    <img src="docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
+    <img src="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
   </picture>
 </p>
 
@@ -63,6 +64,12 @@ PortLearn is under active research development. This roadmap is intentionally hi
 - Chronologically valid feature transforms: lags, rolling statistics, scalers, and carry-forward.
 - Contracts for the forecasting and estimation lifecycle (fitting, refitting, forecast timing, tuning, seeds, determinism, provenance); estimators are not provided yet.
 - Descriptive research-dataset diagnostics (summary, correlation, coverage, missingness) with renderer-neutral plotting; rendering is available through the optional `plot` extra.
+- Portfolio weights: target-weight validation, weight books, and the closed portfolio-role vocabulary, under the `portlearn.weights` module.
+- Rebalancing: schedule policies and the drift law that carries held weights across holding segments (`portlearn.rebalance`).
+- Transaction ledger: segment-composed accounting over the wealth path, built on immutable per-period ledger records with retained execution details, and the reference accounting engine (`portlearn.ledger`).
+- Trading and cost accounting: cost-aware transaction and turnover accounting with proportional cost models (`portlearn.trades`, `portlearn.turnover`, `portlearn.costs`).
+- The strategy decision-contract seam: `Strategy.decide(context) -> DecisionResult` over `DecisionContext` — the decision-time aggregate of forecast, information, holdings, and strategy state — validated by `require_decision_result_compatible`.
+- Strategies: the built-in classical strategies — equal weight, inverse volatility, minimum variance, and mean-variance (`portlearn.strategies`).
 
 **Next**
 
@@ -71,7 +78,6 @@ PortLearn is under active research development. This roadmap is intentionally hi
 
 **Planned**
 
-- 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.

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
-    <img src="docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/monochrome/portlearn-logo-horizontal-white.png">
+    <img src="https://raw.githubusercontent.com/fmasoudy/PortLearn/main/docs/assets/brand/png/primary/portlearn-logo-horizontal.png" alt="PortLearn logo: a rounded navy-and-teal PL monogram with a segmented circular motif, beside the PortLearn wordmark" width="460">
   </picture>
 </p>
 
@@ -47,6 +47,12 @@ PortLearn is under active research development. This roadmap is intentionally hi
 - Chronologically valid feature transforms: lags, rolling statistics, scalers, and carry-forward.
 - Contracts for the forecasting and estimation lifecycle (fitting, refitting, forecast timing, tuning, seeds, determinism, provenance); estimators are not provided yet.
 - Descriptive research-dataset diagnostics (summary, correlation, coverage, missingness) with renderer-neutral plotting; rendering is available through the optional `plot` extra.
+- Portfolio weights: target-weight validation, weight books, and the closed portfolio-role vocabulary, under the `portlearn.weights` module.
+- Rebalancing: schedule policies and the drift law that carries held weights across holding segments (`portlearn.rebalance`).
+- Transaction ledger: segment-composed accounting over the wealth path, built on immutable per-period ledger records with retained execution details, and the reference accounting engine (`portlearn.ledger`).
+- Trading and cost accounting: cost-aware transaction and turnover accounting with proportional cost models (`portlearn.trades`, `portlearn.turnover`, `portlearn.costs`).
+- The strategy decision-contract seam: `Strategy.decide(context) -> DecisionResult` over `DecisionContext` — the decision-time aggregate of forecast, information, holdings, and strategy state — validated by `require_decision_result_compatible`.
+- Strategies: the built-in classical strategies — equal weight, inverse volatility, minimum variance, and mean-variance (`portlearn.strategies`).
 
 **Next**
 
@@ -55,7 +61,6 @@ PortLearn is under active research development. This roadmap is intentionally hi
 
 **Planned**
 
-- 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.

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/examples/foundation_contract_wiring.py

@@ -97,7 +97,7 @@ def main() -> None:
     print(f"[4] lineage: {derived_feature.series_id} accepted (not available before its input)")
 
     # [5] Information-leakage battery: each synthetic leak attempt must be
-    # blocked by its frozen contract error.
+    # blocked by its fixed contract error.
     report = run_leakage_cases([
         LeakageCase(
             name="admit an observation not yet available at the decision",
@@ -129,7 +129,7 @@ def main() -> None:
     print(f"[6] manifest: {canonical}")
     print(f"    round-trips unchanged: {RunManifest.from_json(canonical) == manifest}")
     print("\nComposition complete: the foundation contracts compose, and the")
-    print("synthetic leak attempts were blocked by the frozen contracts.")
+    print("synthetic leak attempts were blocked by the fixed contract.")
 
 
 if __name__ == "__main__":

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/examples/information_set_smoke.py

@@ -13,7 +13,7 @@ Offline and side-effect free: importing this module executes nothing;
 every read is a committed fixture under ``tests/adapters/fixtures``,
 no network is touched, no file is written, and no clock feeds the data
 path — every retrieval instant is a fixed fixture-derived constant, so
-repeated replays print byte-identical summaries.
+repeated replays print identical summaries.
 """
 
 from __future__ import annotations
@@ -230,7 +230,7 @@ def compose_replay() -> types.SimpleNamespace:
         metadata_bytes=FRED_DFFD_META.read_bytes(),
     )
 
-    # Daily-derived monthly feature: the frozen rolling transform over
+    # Daily-derived monthly feature: the fixed rolling transform over
     # the daily factor leg, lineage-checked at each output's own window.
     feature_inputs = sorted(
         (
@@ -268,7 +268,7 @@ def compose_replay() -> types.SimpleNamespace:
 
     # Alignment: one store over every decoded family, one month-end
     # decision instant from the calendar builder, and the requested
-    # observation groups admitted through the frozen vintage operation.
+    # observation groups admitted through the strict vintage operation.
     store = ObservationStore(
         [*ff_monthly, *ff_daily, *feature_outputs, *cpim, *dffd, *ff49]
     )
@@ -315,7 +315,7 @@ def compose_replay() -> types.SimpleNamespace:
     )
 
     # The leakage battery: future, revision, lineage, and undated-
-    # decision leak attempts, each expected to be blocked by its frozen
+    # decision leak attempts, each expected to be blocked by its fixed
     # contract error.
     naive_decision = datetime(2026, 9, 30)  # noqa: DTZ001 — deliberately naive
     early_feature = TimedObservation(

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/pyproject.toml

@@ -4,15 +4,17 @@
 # The distribution name and the PEP 440 version declared here are the single
 # version authority for the package.
 name = "portlearn"
-version = "0.0.1.dev1"
+version = "0.0.1.dev3"
 
 # Minimum supported Python; no untested upper-version exclusion.
 requires-python = ">=3.11"
 
-# Runtime dependencies: pandas is the sole unconditional core runtime
-# dependency — evidence-supported floor
-# (first Python-3.13-compatible release), no upper cap.
-dependencies = ["pandas>=2.2.3"]
+# Runtime dependencies: pandas and scipy are the unconditional core
+# runtime dependencies — evidence-supported floors, no upper caps.
+# SciPy is core: it backs the minimum-variance and
+# mean-variance strategies, but is imported lazily inside the private
+# optimizer adapter, never at package import.
+dependencies = ["pandas>=2.2.3", "scipy>=1.14"]
 
 # Public packaging metadata (PEP 621): one-line description of present
 # functionality only; README and licence referenced, never duplicated.
@@ -25,16 +27,20 @@ license = "Apache-2.0"
 Repository = "https://github.com/fmasoudy/PortLearn"
 Issues = "https://github.com/fmasoudy/PortLearn/issues"
 
-# The two optional capability groups:
+# The optional capability groups:
 # pyarrow is pulled only by portlearn[parquet] and matplotlib only by
 # portlearn[plot]; neither is ever imported by the core package.
+# (The former portlearn[optimization] extra was removed
+# when SciPy became a core dependency.)
 [project.optional-dependencies]
 parquet = ["pyarrow>=21.0.0,<26"]
 plot = ["matplotlib>=3.9.2"]
 
-# Development dependencies: the test harness, the source-quality checker,
-# and the plotting stack at exactly the plot-extra requirement,
-# so a development environment can exercise the renderer.
+# Development dependencies: the test harness, the source-quality
+# checker, and a dev mirror of the plot extra (matplotlib at exactly
+# the plot-extra requirement) so a development environment can
+# exercise the renderer test path. scipy no longer needs a dev mirror:
+# it is an unconditional core runtime dependency.
 [dependency-groups]
 dev = [
     "pytest>=9.1.1,<10",

{portlearn-0.0.1.dev1 → portlearn-0.0.1.dev3}/scripts/verify_built_wheel.py

@@ -1,4 +1,4 @@
-"""Fail-closed verification of the PortLearn distribution built by ``uv build``.
+"""Strict verification of the PortLearn distribution built by ``uv build``.
 
 Executed verbatim after the build::
 
@@ -11,7 +11,7 @@ ambiguity:
 
 1. exactly one wheel and one source distribution produced by ``uv build``
    exist under ``dist/``;
-2. the wheel contains the complete package surface — the static frozen
+2. the wheel contains the complete package surface — the static fixed
    floor of contract modules plus every shippable file currently under
    ``src/portlearn/`` (``.py`` modules and the ``py.typed`` marker,
    derived recursively so subpackages are included) — so a wheel missing
@@ -64,13 +64,13 @@ LOCK_PATH = REPOSITORY_ROOT / "uv.lock"
 DISTRIBUTION_NAME = "portlearn"
 PACKAGE_SOURCE_ROOT = REPOSITORY_ROOT / "src" / DISTRIBUTION_NAME
 
-#: The frozen contract floor a built wheel must always carry, whatever the
+#: The fixed contract floor a built wheel must always carry, whatever the
 #: source tree later adds: the seven foundation members plus the public
 #: diagnostics subpackage marker. A source-tree deletion cannot shrink this
-#: floor, so a wheel missing any frozen contract module — or silently
+#: floor, so a wheel missing any fixed contract module — or silently
 #: omitting the entire diagnostics subpackage — fails verification even
 #: when the derived surface has moved on. Only the public package marker
-#: is frozen: exact private per-block filenames are implementation detail
+#: is fixed: exact private per-block filenames are implementation detail
 #: and join through the recursive derivation alone. Pinned by
 #: ``tests/test_package_contract.py::test_required_wheel_members_cover_the_complete_package_surface``.
 REQUIRED_FLOOR_MEMBERS = (
@@ -91,10 +91,10 @@ def _derived_package_surface() -> tuple[str, ...]:
     Derivation (not enumeration) keeps this the single source of truth:
     a module or subpackage added to the source tree joins
     the required wheel surface automatically, so the check can never again
-    go stale — a new module colliding with a frozen static list is the exact
+    go stale — a new module colliding with a pinned static list is the exact
     defect class this hybrid cures. Recursion (``rglob``) includes
     subpackages, so a wheel silently omitting an entire subpackage fails.
-    Fail-closed: an unreadable or empty source tree is an error, never a
+    Strict rejection: an unreadable or empty source tree is an error, never a
     vacuous pass.
     """
     if not PACKAGE_SOURCE_ROOT.is_dir():
@@ -115,9 +115,9 @@ def _derived_package_surface() -> tuple[str, ...]:
     return tuple(sorted(members))
 
 
-#: The complete surface a built wheel must carry: the frozen floor UNION the
+#: The complete surface a built wheel must carry: the fixed floor UNION the
 #: recursively derived source surface — additions auto-join (derivation),
-#: deletions of frozen contract modules stay detected (floor). Pinned by
+#: deletions of fixed contract modules stay detected (floor). Pinned by
 #: ``tests/test_package_contract.py::test_required_wheel_members_cover_the_complete_package_surface``.
 REQUIRED_WHEEL_MEMBERS = tuple(
     sorted(set(REQUIRED_FLOOR_MEMBERS) | set(_derived_package_surface()))
@@ -190,7 +190,7 @@ def declared_version() -> str:
 
 
 def locate_distribution_artifacts() -> tuple[Path, Path]:
-    """Return (wheel, sdist) — exactly one of each, else fail closed."""
+    """Return (wheel, sdist) — exactly one of each, else abort."""
     if not DIST_DIRECTORY.is_dir():
         fail("dist/ does not exist; run `uv build` first")
 

portlearn-0.0.1.dev3/src/portlearn/__init__.py

@@ -0,0 +1,67 @@
+"""PortLearn — research infrastructure for portfolio-learning research.
+
+This package ships its public identity only: importing this module is
+side-effect-free — it performs no filesystem writes, network access,
+configuration changes, logging initialization, data retrieval, or
+application computation — and it eagerly imports no other PortLearn
+module, so the import surface stays minimal and stable.
+
+``pyproject.toml`` is the single version authority: ``__version__`` is
+derived from the installed distribution metadata rather than
+hard-coded, so it can never drift from the declared release.
+"""
+
+from __future__ import annotations
+
+from importlib import metadata
+from typing import Any
+
+__version__ = metadata.version("portlearn")
+
+__all__ = ["__version__", "data", "weights"]
+
+
+def __getattr__(name: str) -> Any:
+    """Lazily import the public module facades (PEP 562)."""
+    if name == "data":
+        from importlib import import_module
+
+        return import_module("portlearn.data")
+    if name == "weights":
+        from importlib import import_module
+
+        return import_module("portlearn.weights")
+    if name == "rebalance":
+        from importlib import import_module
+
+        return import_module("portlearn.rebalance")
+    if name == "trades":
+        from importlib import import_module
+
+        return import_module("portlearn.trades")
+    if name == "turnover":
+        from importlib import import_module
+
+        return import_module("portlearn.turnover")
+    if name == "costs":
+        from importlib import import_module
+
+        return import_module("portlearn.costs")
+    if name == "ledger":
+        from importlib import import_module
+
+        return import_module("portlearn.ledger")
+    if name == "strategies":
+        from importlib import import_module
+
+        return import_module("portlearn.strategies")
+    raise AttributeError(
+        f"module {__name__!r} has no attribute {name!r}; the lazily "
+        "exposed public subpackage is 'data'; the public modules are "
+        "'weights', 'rebalance', 'trades', 'turnover', 'costs', "
+        "'ledger', and 'strategies'."
+    )
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

portlearn-0.0.1.dev3/src/portlearn/_allocation.py

@@ -0,0 +1,206 @@
+"""Private allocation engine: long-only minimum- and mean-variance entry
+points."""
+
+from __future__ import annotations
+
+import math
+import numbers
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from portlearn._optimizer_adapters.scipy_adapter import ScipySolveResult
+
+
+def solve_long_only_min_variance(
+    covariance: Sequence[Sequence[float]],
+    identifiers: Sequence[str],
+) -> ScipySolveResult:
+    """Validate inputs and delegate the long-only minimum-variance solve.
+
+    Validation performed here is exact (no numerical tolerance): the
+    covariance matrix must be square with shape matching ``identifiers``,
+    identifiers must be unique, and the matrix must be exactly symmetric.
+    Only after validation passes is the optimizer adapter imported, so
+    malformed input never depends on the optional optimization extra.
+
+    Args:
+        covariance: Symmetric covariance matrix with shape ``(N, N)`` matching
+            ``identifiers``.
+        identifiers: Ordered, unique identifiers, one per row/column of
+            ``covariance``.
+
+    Returns:
+        The immutable solve result produced by the optimizer adapter.
+
+    Raises:
+        ValueError: If any validation check fails.
+        OptimizationUnavailableError: If SciPy is not installed
+            (propagated from the adapter).
+        OptimizationFailureError: If the backend fails (propagated from the
+            adapter).
+    """
+    n = len(identifiers)
+    if n == 0:
+        message = "identifiers must name at least one asset"
+        raise ValueError(message)
+
+    if len(covariance) != n:
+        message = (
+            f"covariance shape mismatch: expected {n} rows for {n} "
+            f"identifiers, got {len(covariance)} rows"
+        )
+        raise ValueError(message)
+
+    for index, row in enumerate(covariance):
+        if len(row) != n:
+            message = f"covariance row {index} has length {len(row)}; expected {n}"
+            raise ValueError(message)
+
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for name in identifiers:
+        if name in seen:
+            duplicates.add(name)
+        else:
+            seen.add(name)
+    if duplicates:
+        message = f"identifiers must be unique; duplicates: {sorted(duplicates)}"
+        raise ValueError(message)
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            if covariance[i][j] != covariance[j][i]:
+                message = (
+                    "covariance must be exactly symmetric: "
+                    f"covariance[{i}][{j}] == {covariance[i][j]!r} but "
+                    f"covariance[{j}][{i}] == {covariance[j][i]!r}"
+                )
+                raise ValueError(message)
+
+    # Late lookup: the adapter (and its SciPy dependency) is only
+    # imported after every input validation check has passed.
+    from portlearn._optimizer_adapters import scipy_adapter
+
+    return scipy_adapter.solve(covariance, identifiers)
+
+
+def solve_long_only_mean_variance(
+    covariance: Sequence[Sequence[float]],
+    expected_returns: Sequence[float],
+    risk_aversion: float,
+    identifiers: Sequence[str],
+) -> ScipySolveResult:
+    """Validate inputs and delegate the long-only mean-variance solve.
+
+    Validation performed here is exact (no numerical tolerance): the
+    covariance matrix must be square with shape matching
+    ``identifiers``, identifiers must be unique, the matrix must be
+    exactly symmetric, ``expected_returns`` must be a length-``N``
+    sequence of real finite numbers, and ``risk_aversion`` must be a
+    finite strictly-positive real number. Only after validation passes
+    is the optimizer adapter imported, so malformed input never
+    depends on the optional optimization extra.
+
+    Args:
+        covariance: Symmetric covariance matrix with shape ``(N, N)``
+            matching ``identifiers``.
+        expected_returns: Expected-return vector of length ``N`` in
+            ``identifiers`` order.
+        risk_aversion: Finite strictly-positive risk-aversion scalar.
+        identifiers: Ordered, unique identifiers, one per row/column of
+            ``covariance``.
+
+    Returns:
+        The immutable solve result produced by the optimizer adapter,
+        carried verbatim (no reordering, no wrapping).
+
+    Raises:
+        ValueError: If any validation check fails.
+        OptimizationUnavailableError: If SciPy is not installed
+            (propagated from the adapter).
+        OptimizationFailureError: If the backend fails (propagated from
+            the adapter).
+    """
+    n = len(identifiers)
+    if n == 0:
+        message = "identifiers must name at least one asset"
+        raise ValueError(message)
+
+    if len(covariance) != n:
+        message = (
+            f"covariance shape mismatch: expected {n} rows for {n} "
+            f"identifiers, got {len(covariance)} rows"
+        )
+        raise ValueError(message)
+
+    for index, row in enumerate(covariance):
+        if len(row) != n:
+            message = f"covariance row {index} has length {len(row)}; expected {n}"
+            raise ValueError(message)
+
+    seen: set[str] = set()
+    duplicates: set[str] = set()
+    for name in identifiers:
+        if name in seen:
+            duplicates.add(name)
+        else:
+            seen.add(name)
+    if duplicates:
+        message = f"identifiers must be unique; duplicates: {sorted(duplicates)}"
+        raise ValueError(message)
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            if covariance[i][j] != covariance[j][i]:
+                message = (
+                    "covariance must be exactly symmetric: "
+                    f"covariance[{i}][{j}] == {covariance[i][j]!r} but "
+                    f"covariance[{j}][{i}] == {covariance[j][i]!r}"
+                )
+                raise ValueError(message)
+
+    if len(expected_returns) != n:
+        message = (
+            f"expected_returns length mismatch: expected {n} entries for "
+            f"{n} identifiers, got {len(expected_returns)} entries"
+        )
+        raise ValueError(message)
+    for index, value in enumerate(expected_returns):
+        if isinstance(value, bool) or not isinstance(value, numbers.Real):
+            message = (
+                "expected_returns entries must be real numbers; entry "
+                f"{index} is {type(value).__name__}"
+            )
+            raise ValueError(  # noqa: TRY004 — the rejection surface is ValueError-only, mirroring the solve law
+                message
+            )
+        if not math.isfinite(float(value)):
+            message = (
+                "expected_returns entries must be finite; entry "
+                f"{index} ({identifiers[index]}) is {value!r}"
+            )
+            raise ValueError(message)
+
+    if isinstance(risk_aversion, bool) or not isinstance(risk_aversion, numbers.Real):
+        message = (
+            f"risk_aversion must be a real number; got {type(risk_aversion).__name__}"
+        )
+        raise ValueError(  # noqa: TRY004 — the rejection surface is ValueError-only, mirroring the solve law
+            message
+        )
+    risk_aversion_float = float(risk_aversion)
+    if not math.isfinite(risk_aversion_float):
+        message = f"risk_aversion must be finite; got {risk_aversion!r}"
+        raise ValueError(message)
+    if risk_aversion_float <= 0.0:
+        message = f"risk_aversion must be strictly positive; got {risk_aversion!r}"
+        raise ValueError(message)
+
+    # Late lookup: the adapter (and its SciPy dependency) is only
+    # imported after every input validation check has passed.
+    from portlearn._optimizer_adapters import scipy_adapter
+
+    return scipy_adapter.solve_mean_variance(
+        covariance, expected_returns, risk_aversion_float, identifiers
+    )

portlearn-0.0.1.dev3/src/portlearn/_optimizer_adapters/__init__.py

@@ -0,0 +1,6 @@
+"""Internal optimizer adapter package for :mod:`portlearn`.
+
+This package is an internal implementation detail of the allocation engine
+and intentionally exports nothing; adapter modules are addressed directly by
+their private names.
+"""