validmind 2.11.0__tar.gz → 2.12.1__tar.gz

{validmind-2.11.0 → validmind-2.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validmind
-Version: 2.11.0
+Version: 2.12.1
 Summary: ValidMind Library
 License: DUAL LICENSE NOTICE
          
@@ -710,7 +710,7 @@ Provides-Extra: pii-detection
 Provides-Extra: pytorch
 Provides-Extra: stats
 Provides-Extra: xgboost
-Requires-Dist: aiohttp[speedups]
+Requires-Dist: aiohttp[speedups] (<3.13.1)
 Requires-Dist: anywidget
 Requires-Dist: arch ; extra == "all"
 Requires-Dist: arch ; extra == "stats"
@@ -718,7 +718,7 @@ Requires-Dist: beautifulsoup4
 Requires-Dist: bert-score (>=0.3.13) ; extra == "all"
 Requires-Dist: bert-score (>=0.3.13) ; extra == "nlp"
 Requires-Dist: datasets (>=2.10.0,<3.0.0) ; extra == "datasets"
-Requires-Dist: deepeval (>3.3.9) ; extra == "llm"
+Requires-Dist: deepeval (>=3.7.0) ; extra == "llm"
 Requires-Dist: evaluate ; extra == "all"
 Requires-Dist: evaluate ; extra == "nlp"
 Requires-Dist: ipywidgets
@@ -735,7 +735,7 @@ Requires-Dist: nltk (>=3.8.1,<4.0.0) ; extra == "nlp"
 Requires-Dist: numpy (>=1.23,<2.0.0)
 Requires-Dist: openai (>=1)
 Requires-Dist: pandas (>=2.0.3,<3.0.0)
-Requires-Dist: plotly (>=5.0.0,<6.0.0)
+Requires-Dist: plotly (>=6.0.0)
 Requires-Dist: polars
 Requires-Dist: presidio-analyzer ; extra == "pii-detection"
 Requires-Dist: presidio-structured ; extra == "pii-detection"
@@ -750,16 +750,16 @@ Requires-Dist: rouge (>=1) ; extra == "nlp"
 Requires-Dist: scikit-learn
 Requires-Dist: scipy ; extra == "all"
 Requires-Dist: scipy ; extra == "stats"
-Requires-Dist: scorecardpy (>=0.1.9.6,<0.2.0) ; extra == "all"
-Requires-Dist: scorecardpy (>=0.1.9.6,<0.2.0) ; extra == "credit-risk"
+Requires-Dist: scorecardpy (==0.1.9.6) ; extra == "all"
+Requires-Dist: scorecardpy (==0.1.9.6) ; extra == "credit-risk"
 Requires-Dist: seaborn
 Requires-Dist: sentencepiece (>=0.2.0,<0.3.0) ; extra == "all"
 Requires-Dist: sentencepiece (>=0.2.0,<0.3.0) ; extra == "huggingface"
 Requires-Dist: sentencepiece (>=0.2.0,<0.3.0) ; extra == "llm"
 Requires-Dist: shap (>=0.46.0) ; extra == "all"
 Requires-Dist: shap (>=0.46.0) ; extra == "explainability"
-Requires-Dist: statsmodels ; extra == "all"
-Requires-Dist: statsmodels ; extra == "stats"
+Requires-Dist: statsmodels (>=0.14.2,<0.15.0) ; extra == "all"
+Requires-Dist: statsmodels (>=0.14.2,<0.15.0) ; extra == "stats"
 Requires-Dist: tabulate (>=0.9.0,<0.10.0)
 Requires-Dist: textblob (>=0.18.0.post0,<0.19.0) ; extra == "all"
 Requires-Dist: textblob (>=0.18.0.post0,<0.19.0) ; extra == "nlp"

{validmind-2.11.0 → validmind-2.12.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "validmind"
-version = "2.11.0"
+version = "2.12.1"
 description = "ValidMind Library"
 readme = "README.pypi.md"
 requires-python = ">=3.9,<3.13"
@@ -13,7 +13,7 @@ authors = [
   { name = "John Walz", email = "john@validmind.ai" },
 ]
 dependencies = [
-  "aiohttp[speedups]",
+  "aiohttp[speedups] (<3.13.1)",
   "ipywidgets",
   "kaleido (>=0.2.1,!=0.2.1.post1,<1.0.0)",
   "matplotlib",
@@ -22,7 +22,7 @@ dependencies = [
   "numpy (>=1.23,<2.0.0)",
   "openai (>=1)",
   "pandas (>=2.0.3,<3.0.0)",
-  "plotly (>=5.0.0,<6.0.0)",
+  "plotly (>=6.0.0)",
   "polars",
   "python-dotenv",
   "scikit-learn",
@@ -44,7 +44,7 @@ all = [
   "sentencepiece (>=0.2.0,<0.3.0)",
   "langchain-openai (>=0.1.8)",
   "scipy",
-  "statsmodels",
+  "statsmodels (>=0.14.2,<0.15.0)",
   "langdetect",
   "nltk (>=3.8.1,<4.0.0)",
   "textblob (>=0.18.0.post0,<0.19.0)",
@@ -53,7 +53,7 @@ all = [
   "bert-score (>=0.3.13)",
   "arch",
   "shap (>=0.46.0)",
-  "scorecardpy (>=0.1.9.6,<0.2.0)",
+  "scorecardpy==0.1.9.6",
 ]
 huggingface = [
   "transformers (>=4.32.0,<5.0.0)",
@@ -66,7 +66,7 @@ llm = [
   "ragas (>=0.2.3,<=0.2.7)",
   "sentencepiece (>=0.2.0,<0.3.0)",
   "langchain-openai (>=0.1.8)",
-  "deepeval (>3.3.9)",
+  "deepeval (>=3.7.0)",
 ]
 nlp = [
   "langdetect",
@@ -78,10 +78,10 @@ nlp = [
   "pyarrow (<16)",
 ]
 pytorch = ["torch (>=2.0.0)"]
-stats = ["scipy", "statsmodels", "arch"]
+stats = ["scipy", "statsmodels (>=0.14.2,<0.15.0)", "arch"]
 xgboost = ["xgboost (>=1.5.2,<3)"]
 explainability = ["shap (>=0.46.0)"]
-credit_risk = ["scorecardpy (>=0.1.9.6,<0.2.0)"]
+credit_risk = ["scorecardpy==0.1.9.6"]
 datasets = ["datasets (>=2.10.0,<3.0.0)"]
 pii-detection = ["presidio-analyzer", "presidio-structured"]
 

{validmind-2.11.0 → validmind-2.12.1}/validmind/__init__.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """
@@ -48,9 +48,9 @@ try:
 except ImportError:
     ...
 
-from . import scorer
+from . import scorers as scorer
 from .__version__ import __version__  # noqa: E402
-from .api_client import init, log_metric, log_text, reload
+from .api_client import init, log_metric, log_test_result, log_text, reload
 from .client import (  # noqa: E402
     get_test_suite,
     init_dataset,
@@ -143,6 +143,7 @@ __all__ = [  # noqa
     "unit_metrics",
     "test_suites",
     "log_text",
+    "log_test_result",
     # experimental features
     "experimental_agent",
 ]

validmind-2.12.1/validmind/__version__.py

@@ -0,0 +1 @@
+__version__ = "2.12.1"

{validmind-2.11.0 → validmind-2.12.1}/validmind/ai/test_descriptions.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import json

{validmind-2.11.0 → validmind-2.12.1}/validmind/ai/utils.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/api_client.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """ValidMind API client
@@ -19,6 +19,7 @@ import aiohttp
 import requests
 from aiohttp import FormData
 
+from .__version__ import __version__
 from .client_config import client_config
 from .errors import MissingAPICredentialsError, MissingModelIdError, raise_api_error
 from .logging import get_logger, log_api_operation
@@ -31,6 +32,7 @@ _api_key = os.getenv("VM_API_KEY")
 _api_secret = os.getenv("VM_API_SECRET")
 _api_host = os.getenv("VM_API_HOST")
 _model_cuid = os.getenv("VM_API_MODEL")
+_document = None
 _monitoring = False
 
 __api_session: Optional[aiohttp.ClientSession] = None
@@ -67,12 +69,16 @@ def get_api_model() -> Optional[str]:
 
 
 def _get_api_headers() -> Dict[str, str]:
-    return {
+    headers = {
         "X-API-KEY": _api_key,
         "X-API-SECRET": _api_secret,
         "X-MODEL-CUID": _model_cuid,
         "X-MONITORING": str(_monitoring),
+        "X-LIBRARY-VERSION": __version__,
     }
+    if _document:
+        headers["X-DOCUMENT-TYPE"] = _document
+    return headers
 
 
 def _get_session() -> aiohttp.ClientSession:
@@ -194,6 +200,7 @@ def init(
     model: Optional[str] = None,
     monitoring: bool = False,
     generate_descriptions: Optional[bool] = None,
+    document: Optional[str] = None,
 ):
     """
     Initializes the API client instances and calls the /ping endpoint to ensure
@@ -209,11 +216,12 @@ def init(
         api_secret (str, optional): The API secret. Defaults to None.
         api_host (str, optional): The API host. Defaults to None.
         monitoring (bool): The ongoing monitoring flag. Defaults to False.
-        generate_descriptions (bool): Whether to use GenAI to generate test result descriptions. Defaults to True.
+        generate_descriptions (bool, optional): Whether to use GenAI to generate test result descriptions. Defaults to True.
+        document (str, optional): The name of the document. Omitting this argument is deprecated.
     Raises:
         ValueError: If the API key and secret are not provided
     """
-    global _api_key, _api_secret, _api_host, _model_cuid, _monitoring
+    global _api_key, _api_secret, _api_host, _model_cuid, _monitoring, _document
 
     if api_key == "...":
         # special case to detect when running a notebook placeholder (...)
@@ -238,6 +246,13 @@ def init(
     if generate_descriptions is not None:
         os.environ["VALIDMIND_LLM_DESCRIPTIONS_ENABLED"] = str(generate_descriptions)
 
+    if document is None:
+        logger.error(
+            "Future releases will require `document` as one of the options you must provide to `vm.init()`. "
+            "To learn more, refer to https://docs.validmind.ai/developer/validmind-library.html"
+        )
+
+    _document = document
     reload()
 
 
@@ -365,6 +380,35 @@ async def alog_test_result(
         raise e
 
 
+def log_test_result(
+    result: Dict[str, Any],
+    section_id: str = None,
+    position: int = None,
+    unsafe: bool = False,
+    config: Dict[str, bool] = None,
+) -> Dict[str, Any]:
+    """Logs test results information.
+
+    Args:
+        result (dict): A dictionary representing the test result.
+        section_id (str, optional): The section ID add a test driven block to the documentation.
+        position (int): The position in the section to add the test driven block.
+        unsafe (bool): If True, log the result even if it contains sensitive data.
+        config (Dict[str, bool]): Configuration options for displaying the test result.
+
+    Returns:
+        dict: The response from the API.
+    """
+    return run_async(
+        alog_test_result,
+        result=result,
+        section_id=section_id,
+        position=position,
+        unsafe=unsafe,
+        config=config,
+    )
+
+
 async def alog_input(
     input_id: str, type: str, metadata: Dict[str, Any]
 ) -> Dict[str, Any]:

{validmind-2.11.0 → validmind-2.12.1}/validmind/client.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

{validmind-2.11.0 → validmind-2.12.1}/validmind/client_config.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

validmind-2.12.1/validmind/datasets/__init__.py

@@ -0,0 +1,7 @@
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+
+"""
+Example datasets that can be used with the ValidMind Library.
+"""

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/classification/__init__.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/classification/customer_churn.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/classification/taiwan_credit.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/cluster/digits.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/credit_risk/__init__.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/credit_risk/lending_club.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import logging
@@ -20,14 +20,12 @@ from validmind.errors import MissingDependencyError
 try:
     import scorecardpy as sc
 except ImportError as e:
-    if "scorecardpy" in str(e):
-        raise MissingDependencyError(
-            "Missing required package `scorecardpy` for credit risk demos. "
-            "Please run `pip install validmind[credit_risk]` or `pip install scorecardpy`.",
-            required_dependencies=["scorecardpy"],
-            extra="credit_risk",
-        ) from e
-    raise e
+    raise MissingDependencyError(
+        "Missing required package `scorecardpy` for credit risk demos. "
+        "Please run `pip install validmind[credit_risk]` or `pip install scorecardpy`.",
+        required_dependencies=["scorecardpy"],
+        extra="credit_risk",
+    ) from e
 
 current_path = os.path.dirname(os.path.abspath(__file__))
 dataset_path = os.path.join(current_path, "datasets")
@@ -516,7 +514,7 @@ def get_demo_test_config(
         "inputs": {
             "dataset": "raw_dataset",
         },
-        "params": {"min_threshold": 1},
+        "params": {"min_percentage_threshold": 1},
     }
     default_config["validmind.data_validation.ClassImbalance:raw_data"] = {
         "inputs": {
@@ -584,7 +582,7 @@ def get_demo_test_config(
         "inputs": {
             "dataset": "preprocess_dataset",
         },
-        "params": {"min_threshold": 1},
+        "params": {"min_percentage_threshold": 1},
     }
     default_config[
         "validmind.data_validation.TabularNumericalHistograms:preprocessed_data"

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/credit_risk/lending_club_bias.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/llm/__init__.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/llm/agent_dataset.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """
@@ -103,6 +103,18 @@ class LLMAgentDataset(VMDataset):
         # Convert to pandas DataFrame for VMDataset compatibility
         df = self._convert_to_dataframe()
 
+        # Build extra_columns only for columns that exist in the DataFrame
+        possible_extra_columns = [
+            "actual_output",
+            "context",
+            "retrieval_context",
+            "tools_called",
+            "expected_tools",
+        ]
+        extra_columns = {
+            col: col for col in possible_extra_columns if col in df.columns
+        }
+
         # Initialize VMDataset with the converted data
         super().__init__(
             raw_dataset=df.values,
@@ -110,13 +122,7 @@ class LLMAgentDataset(VMDataset):
             columns=df.columns.tolist(),
             text_column="input",  # The input text for LLM
             target_column="expected_output",  # Expected response
-            extra_columns={
-                "actual_output": "actual_output",
-                "context": "context",
-                "retrieval_context": "retrieval_context",
-                "tools_called": "tools_called",
-                "expected_tools": "expected_tools",
-            },
+            extra_columns=extra_columns if extra_columns else None,
             **kwargs,
         )
 

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/llm/rag/__init__.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/llm/rag/rfp.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/nlp/__init__.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/nlp/cnn_dailymail.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/nlp/twitter_covid_19.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 import os

{validmind-2.11.0 → validmind-2.12.1}/validmind/datasets/regression/__init__.py

@@ -1,5 +1,5 @@
-# Copyright © 2023-2024 ValidMind Inc. All rights reserved.
-# See the LICENSE file in the root of this repository for details.
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
 # SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
 
 """

validmind-2.12.1/validmind/datasets/regression/california_housing.py

@@ -0,0 +1,137 @@
+# Copyright © 2023-2026 ValidMind Inc. All rights reserved.
+# Refer to the LICENSE file in the root of this repository for details.
+# SPDX-License-Identifier: AGPL-3.0 AND ValidMind Commercial
+
+import os
+from urllib.error import HTTPError, URLError
+
+import pandas as pd
+from sklearn.datasets import fetch_california_housing
+from sklearn.model_selection import train_test_split
+
+current_path = os.path.dirname(os.path.abspath(__file__))
+dataset_path = os.path.join(current_path, "datasets")
+
+feature_columns = ["HouseAge", "AveRooms", "AveBedrms", "Population", "AveOccup"]
+target_column = "MedHouseVal"
+
+# Path to bundled dataset file
+bundled_data_file = os.path.join(dataset_path, "california_housing.csv")
+
+
+def load_data(full_dataset=False, source: str = "bundled"):
+    """
+    Load the California housing dataset.
+
+    This function first attempts to load from a bundled dataset file in the repository.
+    If the bundled file is not available, it falls back to sklearn's fetch function
+    (which uses cache or attempts download).
+
+    Args:
+        full_dataset: Not currently used, kept for API compatibility.
+        source: 'bundled' to load from repository file (default), 'sklearn' to use sklearn's fetch.
+
+    Returns:
+        pd.DataFrame: DataFrame containing the California housing data.
+
+    Raises:
+        RuntimeError: If the dataset cannot be loaded from bundled file or downloaded.
+        FileNotFoundError: If bundled file is requested but not found.
+    """
+    if source == "bundled":
+        # Try to load from bundled dataset file
+        if os.path.exists(bundled_data_file):
+            df = pd.read_csv(bundled_data_file)
+            # Ensure we have the correct columns
+            required_cols = feature_columns + [target_column]
+            if all(col in df.columns for col in required_cols):
+                return df[required_cols]
+            else:
+                # If columns don't match, fall back to sklearn
+                return _load_from_sklearn()
+        else:
+            # Bundled file not found, fall back to sklearn
+            return _load_from_sklearn()
+    elif source == "sklearn":
+        return _load_from_sklearn()
+    else:
+        raise ValueError("Invalid source specified. Choose 'bundled' or 'sklearn'.")
+
+
+def _load_from_sklearn():
+    """
+    Load the California housing dataset from sklearn.
+
+    This function first attempts to load from sklearn's cache. If the dataset
+    is not cached, it attempts to download it. If download fails (e.g., 403 Forbidden),
+    it provides helpful error messages.
+
+    Returns:
+        pd.DataFrame: DataFrame containing the California housing data.
+
+    Raises:
+        RuntimeError: If the dataset cannot be downloaded due to network issues (e.g., 403 Forbidden).
+        URLError: If there's a URL-related error when fetching the dataset.
+        OSError: If the dataset is not cached and cannot be downloaded.
+    """
+    # First, try to load from cache (won't attempt download)
+    try:
+        california_housing = fetch_california_housing(
+            as_frame=True, download_if_missing=False
+        )
+    except OSError:
+        # Dataset not in cache, try to download it
+        try:
+            california_housing = fetch_california_housing(as_frame=True)
+        except HTTPError as e:
+            if (
+                "403" in str(e)
+                or "Forbidden" in str(e)
+                or (hasattr(e, "code") and e.code == 403)
+            ):
+                error_msg = (
+                    "HTTP 403 Forbidden error when downloading California housing dataset.\n\n"
+                    "This is a known issue with sklearn's dataset repository access restrictions.\n\n"
+                    "The dataset should be available as a bundled file in the repository.\n"
+                    "If you're seeing this error, please ensure the bundled dataset file exists\n"
+                    "at: {}\n\n".format(bundled_data_file)
+                    + "Alternatively, you can manually download the dataset from:\n"
+                    "https://www.dcc.fc.up.pt/~ltorgo/Regression/cal_housing.tgz\n"
+                    "and extract it to ~/scikit_learn_data/cal_housing/"
+                )
+                raise RuntimeError(error_msg) from e
+            else:
+                error_msg = (
+                    f"Failed to download California housing dataset: {str(e)}\n\n"
+                    "This error typically occurs when:\n"
+                    "  1. There's no internet connection\n"
+                    "  2. The sklearn dataset repository is temporarily unavailable\n"
+                    "  3. There's a network firewall blocking the download\n\n"
+                    "The dataset should be automatically cached after the first successful download.\n"
+                    "Please check your network connection and try again."
+                )
+                raise RuntimeError(error_msg) from e
+        except URLError as e:
+            error_msg = (
+                f"URL error when downloading California housing dataset: {str(e)}\n\n"
+                "This typically indicates a network connectivity issue.\n"
+                "Please check your internet connection and try again."
+            )
+            raise URLError(error_msg) from e
+
+    df = california_housing.data[feature_columns]
+    df = df.copy()
+    df[target_column] = california_housing.target.values
+
+    return df
+
+
+def preprocess(df):
+    df = df.copy()
+
+    train_val_df, test_df = train_test_split(df, test_size=0.20)
+
+    # This guarantees a 60/20/20 split
+    train_df, validation_df = train_test_split(train_val_df, test_size=0.25)
+
+    return train_df, validation_df, test_df