Add LLM support, add more examples, update docs, add ensembling

Author: thomasmeissnercrm

README.md

@@ -40,7 +40,8 @@ Here you can see our test coverage in more detail:
     * [v3.0 Breaking Changes](#v30-breaking-changes)
     * [v2.0 Improvements](#v20-improvements)
   * [Convenience features](#convenience-features)
-  * [Kaggle competition results and example notebooks](#kaggle-competition-results-and-example-notebooks)
+  * [Example scripts](#example-scripts)
+  * [Kaggle competition results](#kaggle-competition-results)
 * [About the code](#about-the-code)
   * [Code quality](#code-quality)
   * [Documentation](#documentation)
@@ -73,17 +74,32 @@ uncertainty quantification.
 ### Basic usage
 
 ```sh
-from bluecast.blueprints.cast import BlueCast
-
-automl = BlueCast(
-        class_problem="binary",
-    )
+from bluecast.blueprints.unified import BlueCastAuto
+from bluecast.ensemble.ensemble_config import EnsembleConfig
 
+# Binary classification - single model
+automl = BlueCastAuto(class_problem="binary")
 automl.fit(df_train, target_col="target")
 y_probs, y_classes = automl.predict(df_val)
 
-# predict_proba is also available (also for BlueCastCV)
-y_probs = automl.predict_proba(df_val)
+# Regression with cross-validation and stacking ensemble
+automl = BlueCastAuto(
+    class_problem="regression",
+    use_cross_validation=True,
+    ensemble_config=EnsembleConfig(ensemble_strategy="stacking"),
+)
+automl.fit(df_train, target_col="target")
+y_preds = automl.predict(df_val)
+```
+
+The original per-class imports still work for users who prefer them:
+
+```sh
+from bluecast.blueprints.cast import BlueCast
+
+automl = BlueCast(class_problem="binary")
+automl.fit(df_train, target_col="target")
+y_probs, y_classes = automl.predict(df_val)
 ```
 
 ### Recent Major Improvements
@@ -164,7 +180,25 @@ y_probs, y_classes = automl.predict(df_val)
 It is important to note that df_train contains the target column while
 df_eval does not. The target column is passed separately as y_eval.
 
-### Kaggle competition results and example notebooks
+### Example scripts
+
+The [examples/](examples/) directory contains self-contained scripts
+using synthetic data that demonstrate BlueCast's full feature set:
+
+| Script | Topics |
+| ------ | ------ |
+| [00_full_showcase.py](examples/00_full_showcase.py) | **End-to-end walkthrough of all features** |
+| [01_quick_start.py](examples/01_quick_start.py) | Binary, multiclass, regression, `fit_eval` |
+| [02_cross_validation_and_ensembles.py](examples/02_cross_validation_and_ensembles.py) | `BlueCastCV`, mean blending, stacking, hill climbing |
+| [03_conformal_prediction.py](examples/03_conformal_prediction.py) | Uncertainty quantification, group-conditional intervals |
+| [04_linear_models.py](examples/04_linear_models.py) | Logistic/Ridge/Lasso regression, configurable preprocessing |
+| [05_unified_interface.py](examples/05_unified_interface.py) | `BlueCastAuto` single entry point for all problem types |
+| [06_advanced_customization.py](examples/06_advanced_customization.py) | Custom preprocessing, XGBoost, drift monitoring, experiment tracking, save/load |
+| [07_fairness.py](examples/07_fairness.py) | Fairness auditing, demographic parity, equalized odds, conformal fairness |
+| [08_eda.py](examples/08_eda.py) | Univariate/bivariate plots, PCA, t-SNE, correlations, data quality, leakage detection |
+| [09_bluecast_ai.py](examples/09_bluecast_ai.py) | Multi-agent LLM-powered AutoML (requires API key) |
+
+### Kaggle competition results
 
 Even though BlueCast has been designed to be a lightweight
 automl framework, it still offers the possibilities to
@@ -182,7 +216,7 @@ feature- and performance-wise.
 and adding conformal prediction ([notebook](https://www.kaggle.com/code/thomasmeiner/bluecast-has-conformal-prediction))
 * 26th place in the Kaggle 24h "AutoMl" GrandPrix July 2024 blitz competition ([notebook](https://www.kaggle.com/code/thomasmeiner/automl-grand-prix-bluecast-26th-place-solution))
 
-Please note that some notebooks ran older versions of BlueCast and
+Please note that some Kaggle notebooks ran older versions of BlueCast and
 might not be compatible with the most recent version anymore.
 
 ## About the code

bluecast/__init__.py

@@ -0,0 +1,23 @@
+"""BlueCast - a lightweight AutoML framework."""
+
+from bluecast.blueprints.cast import BlueCast
+from bluecast.blueprints.cast_cv import BlueCastCV
+from bluecast.blueprints.cast_cv_regression import BlueCastCVRegression
+from bluecast.blueprints.cast_regression import BlueCastRegression
+from bluecast.blueprints.unified import BlueCastAuto
+from bluecast.config.training_config import TrainingConfig
+from bluecast.ensemble.ensemble_config import EnsembleConfig
+from bluecast.evaluation.fairness import FairnessAuditor
+from bluecast.experimentation.tracking import ExperimentTracker
+
+__all__ = [
+    "BlueCast",
+    "BlueCastCV",
+    "BlueCastRegression",
+    "BlueCastCVRegression",
+    "BlueCastAuto",
+    "TrainingConfig",
+    "EnsembleConfig",
+    "ExperimentTracker",
+    "FairnessAuditor",
+]

bluecast/ai/__init__.py

@@ -0,0 +1,151 @@
+"""
+BlueCastAI: Multi-agent LLM-powered AutoML.
+
+Optional module -- install dependencies with:
+    pip install bluecast[ai]           # all providers
+    pip install bluecast[ai-gemini]    # Google Gemini only
+    pip install bluecast[ai-openai]    # OpenAI only
+    pip install bluecast[ai-anthropic] # Anthropic Claude only
+
+Usage::
+
+    from bluecast.ai import BlueCastAI
+
+    ai = BlueCastAI(api_key="...", provider="gemini")
+    result = ai.run(df_train, target_col="target",
+                    prompt="Build a precise binary classifier")
+    result.predict(df_test)
+    result.save_code("pipeline.py")
+"""
+
+import logging
+from typing import List, Literal, Optional
+
+import pandas as pd
+
+from bluecast.ai.config import AIConfig
+from bluecast.ai.result import BlueCastAIResult
+
+logger = logging.getLogger(__name__)
+
+
+def _create_provider(config: AIConfig):
+    """Factory to create the right LLM provider based on config."""
+    model = config.get_model_name()
+
+    if config.provider == "gemini":
+        from bluecast.ai.providers.gemini import GeminiProvider
+        return GeminiProvider(api_key=config.api_key, model=model, temperature=config.temperature)
+    elif config.provider == "openai":
+        from bluecast.ai.providers.openai_provider import OpenAIProvider
+        return OpenAIProvider(api_key=config.api_key, model=model, temperature=config.temperature)
+    elif config.provider == "anthropic":
+        from bluecast.ai.providers.anthropic_provider import AnthropicProvider
+        return AnthropicProvider(api_key=config.api_key, model=model, temperature=config.temperature)
+    else:
+        raise ValueError(f"Unknown provider: {config.provider}. Use 'gemini', 'openai', or 'anthropic'.")
+
+
+class BlueCastAI:
+    """Multi-agent LLM-powered AutoML for BlueCast.
+
+    Provide an API key, a dataset, and a natural language prompt.
+    BlueCastAI will analyze the data, engineer features, build a pipeline,
+    evaluate it, and iteratively improve it -- all guided by LLM agents.
+
+    :param api_key: API key for the LLM provider.
+    :param provider: LLM provider: 'gemini', 'openai', or 'anthropic'.
+    :param model: Provider-specific model name (e.g. 'gpt-4o', 'claude-sonnet-4-20250514').
+        Uses a sensible default per provider if not specified.
+    :param enable_web_search: Whether agents can search the web for techniques.
+    :param verbose: Whether to print progress to stdout.
+    :param temperature: LLM temperature (0.0 = deterministic, 1.0 = creative).
+    :param checkpoint_dir: Directory for saving checkpoints. If a run crashes,
+        the next call to .run() with the same checkpoint_dir resumes from where
+        it left off. Set to None to disable checkpointing.
+
+    Usage::
+
+        from bluecast.ai import BlueCastAI
+
+        ai = BlueCastAI(api_key="your-key", provider="gemini")
+        result = ai.run(
+            df_train,
+            target_col="target",
+            prompt="Build a high-precision binary classifier with hill climbing ensemble",
+            mode="precise",
+        )
+
+        # Use the trained pipeline
+        predictions = result.predict(df_test)
+
+        # Export reproducible code
+        result.save_code("my_pipeline.py")
+
+        # View what happened
+        result.show_report()
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        provider: Literal["gemini", "openai", "anthropic"] = "gemini",
+        model: Optional[str] = None,
+        enable_web_search: bool = False,
+        verbose: bool = True,
+        temperature: float = 0.2,
+        checkpoint_dir: Optional[str] = None,
+    ):
+        self.config = AIConfig(
+            api_key=api_key,
+            provider=provider,
+            model=model,
+            enable_web_search=enable_web_search,
+            verbose=verbose,
+            temperature=temperature,
+            checkpoint_dir=checkpoint_dir,
+        )
+        self._llm = _create_provider(self.config)
+
+    def run(
+        self,
+        df: pd.DataFrame,
+        target_col: str,
+        prompt: str = "Build a good model",
+        context_files: Optional[List[str]] = None,
+        mode: Literal["fast", "balanced", "precise"] = "balanced",
+        max_iterations: int = 0,
+    ) -> BlueCastAIResult:
+        """Run the multi-agent pipeline on the dataset.
+
+        :param df: Training DataFrame including the target column.
+        :param target_col: Name of the target column.
+        :param prompt: Natural language instructions for what to build.
+            Examples:
+            - "Build a fast baseline model"
+            - "Build a precise binary classifier with stacking ensemble"
+            - "Maximize ROC AUC using hill climbing and feature engineering"
+        :param context_files: Optional list of file paths containing domain knowledge.
+        :param mode: Speed vs thoroughness trade-off:
+            'fast' = skip FE, 1 iteration (~2 min),
+            'balanced' = targeted FE, 3 iterations (~10 min),
+            'precise' = full FE, ensemble, 5+ iterations (~30 min).
+        :param max_iterations: Override the number of build-evaluate-improve cycles.
+            If 0, uses the mode default.
+        :returns: BlueCastAIResult with trained pipeline, code, metrics, and logs.
+        """
+        self.config.mode = mode
+        self.config.context_files = context_files or []
+        if max_iterations > 0:
+            self.config.max_iterations = max_iterations
+
+        from bluecast.ai.orchestrator import Orchestrator
+
+        orchestrator = Orchestrator(
+            llm=self._llm,
+            config=self.config,
+            df=df,
+            target_col=target_col,
+            prompt=prompt,
+        )
+        return orchestrator.run()

bluecast/ai/agents/__init__.py

@@ -0,0 +1 @@
+"""BlueCastAI agent implementations."""