featune 1.0.0__py3-none-any.whl

featune/__init__.py

@@ -0,0 +1,83 @@
+# SPDX-FileCopyrightText: 2026 Featune contributors
+# SPDX-License-Identifier: MIT
+
+"""Featune public feature search API.
+
+Exports the supported feature-search API and pinned TabPFN adapters while
+keeping heavyweight model and visualization imports lazy.
+
+Created:
+    2026-09-21
+"""
+
+import logging
+
+from .budget import SearchBudget
+from .compiler import FeatureCompiler
+from .context import ContextBudget, ContextBuilder
+from .evaluation import CVEvaluator
+from .fingerprint import ExperimentFingerprint
+from .ir import FeatureIR, FeatureSet
+from .llm import LLMClient
+from .logging_utils import ColorFormatter
+from .memory import SearchMemory, SearchMemoryCompressor
+from .retrieval import (
+    BaseColumnRetriever,
+    ColumnSemanticIndex,
+    HybridColumnRetriever,
+    RandomColumnRetriever,
+    RuleBasedColumnRetriever,
+    SemanticColumnRetriever,
+)
+from .samplers import (
+    AutonomousSampler,
+    BaseFeatureSampler,
+    EvolutionSampler,
+    HybridSampler,
+    LLMSampler,
+    RandomSampler,
+)
+from .schema import DatasetSchema, FeatureSpec, FieldSchema, Hypothesis, Proposal
+from .study import FeatureStudy, Trial, create_study, load_study
+from .tabpfn import TabPFNClassifier, TabPFNRegressor
+
+__version__ = "1.0.0"
+__all__ = [
+    "TabPFNClassifier",
+    "TabPFNRegressor",
+    "ContextBudget",
+    "ContextBuilder",
+    "SearchMemory",
+    "SearchMemoryCompressor",
+    "BaseColumnRetriever",
+    "ColumnSemanticIndex",
+    "SemanticColumnRetriever",
+    "RandomColumnRetriever",
+    "RuleBasedColumnRetriever",
+    "HybridColumnRetriever",
+    "SearchBudget",
+    "ExperimentFingerprint",
+    "FeatureIR",
+    "FeatureSet",
+    "BaseFeatureSampler",
+    "CVEvaluator",
+    "DatasetSchema",
+    "EvolutionSampler",
+    "FeatureCompiler",
+    "FeatureSpec",
+    "FeatureStudy",
+    "FieldSchema",
+    "HybridSampler",
+    "AutonomousSampler",
+    "Hypothesis",
+    "LLMClient",
+    "ColorFormatter",
+    "LLMSampler",
+    "Proposal",
+    "RandomSampler",
+    "Trial",
+    "create_study",
+    "load_study",
+]
+logging.getLogger("featune").addHandler(logging.NullHandler())
+logging.getLogger("featune").setLevel(logging.INFO)

featune/__main__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: 2026 Featune contributors
+# SPDX-License-Identifier: MIT
+
+"""Module entry point.
+
+Delegates python -m featune to the same CLI used by the installed entry point.
+
+Created:
+    2026-09-21
+"""
+
+from .cli import main
+
+main()

featune/budget.py

@@ -0,0 +1,67 @@
+# SPDX-FileCopyrightText: 2026 Featune contributors
+# SPDX-License-Identifier: MIT
+
+"""Persistable search budgets with explicit consumption units.
+
+Separates cumulative search resource ceilings from per-request context limits.
+
+Created:
+    2026-09-21
+"""
+
+from pydantic import Field
+
+from .schema import Contract
+
+
+class SearchBudget(Contract):
+    """Define cumulative resource ceilings, independent of prompt context limits.
+
+    Attributes:
+        max_trials (int or None): Candidate attempts, including failed and duplicate proposals.
+        max_model_fits (int or None): Model-fit attempts, including baseline and final refit.
+        max_wall_time (float or None): Active optimize wall-clock seconds across calls.
+        max_llm_tokens (int or None): Known cumulative input plus output tokens.
+        max_llm_cost (float or None): Estimated API currency units; token prices are required.
+        max_valid_proposals (int or None): Proposals that pass schema and parameter validation.
+
+    Notes:
+        None disables a ceiling. Time is checked between work units, not by interrupting
+        an in-progress third-party fit or HTTP call.
+    """
+
+    max_trials: int | None = Field(default=None, ge=0)
+    max_model_fits: int | None = Field(default=None, ge=0)
+    max_wall_time: float | None = Field(default=None, gt=0)
+    max_llm_tokens: int | None = Field(default=None, ge=0)
+    max_llm_cost: float | None = Field(default=None, ge=0)
+    max_valid_proposals: int | None = Field(default=None, ge=0)
+
+    def exhausted(self, usage: dict) -> str | None:
+        """Find the first configured ceiling reached by current consumption.
+
+        Args:
+            usage (dict): Consumed resources keyed without the max_ prefix; absent entries count as zero.
+
+        Returns:
+            str or None: Exhausted max_ field name, or None when all limits permit work.
+        """
+        for name, limit in self.model_dump().items():
+            if limit is not None and usage.get(name.removeprefix("max_"), 0) >= limit:
+                return name
+        return None
+
+    def remaining(self, usage: dict) -> dict:
+        """Calculate nonnegative remaining capacity for configured ceilings.
+
+        Args:
+            usage (dict): Consumed resources keyed without the max_ prefix; absent entries count as zero.
+
+        Returns:
+            dict[str, int or float]: Resource names without max_; unlimited resources are omitted.
+        """
+        return {
+            name.removeprefix("max_"): max(0, limit - usage.get(name.removeprefix("max_"), 0))
+            for name, limit in self.model_dump().items()
+            if limit is not None
+        }

featune/cache.py

@@ -0,0 +1,119 @@
+# SPDX-FileCopyrightText: 2026 Featune contributors
+# SPDX-License-Identifier: MIT
+
+"""Version-namespaced atomic memoization for trusted local studies.
+
+Stores trusted local joblib artifacts. Namespace compatibility is supplied by
+the caller; this module does not validate external artifact provenance.
+
+Created:
+    2026-09-21
+"""
+
+import uuid
+from pathlib import Path
+
+import joblib
+
+from .ir import content_hash
+
+
+class ArtifactCache:
+    """Memoize trusted artifacts in memory or a versioned local directory.
+
+    Attributes:
+        namespace (str): Experiment namespace separating incompatible artifacts.
+        directory (Path or None): Namespace directory, or None for memory-only caching.
+        memory (dict): In-process entries keyed by layer and key digest.
+        hits (int): Successful get operations since construction.
+        misses (int): Unsuccessful get operations since construction.
+
+    Notes:
+        Disk artifacts use joblib and must never be loaded from untrusted sources.
+        Heavy memory layers retain at most eight insertion-ordered entries each.
+    """
+
+    layers = {"ir", "feature_set", "fold_transform", "matrix", "estimator", "evaluation"}
+
+    def __init__(self, directory=None, namespace="memory"):
+        """Initialize an empty cache and resource counters.
+
+        Args:
+            directory (str, Path, or None): Cache root; None selects in-memory storage.
+            namespace (str): Experiment identity separating incompatible cache entries.
+        """
+        self.namespace = namespace
+        self.directory = Path(directory) / namespace if directory else None
+        self.memory = {}
+        self.hits, self.misses = 0, 0
+
+    def _path(self, layer, key):
+        """Resolve a layer/key to its namespaced artifact path.
+
+        Args:
+            layer (str): One of ir, feature_set, fold_transform, matrix, estimator or evaluation.
+            key (JSON-serializable object): Deterministic artifact identity within the namespace.
+
+        Returns:
+            Path or None: Disk destination, or None in memory mode.
+
+        Raises:
+            ValueError: layer is not a registered cache layer.
+        """
+        if layer not in self.layers:
+            raise ValueError("Unknown cache layer")
+        return self.directory / layer / (content_hash(key) + ".joblib") if self.directory else None
+
+    def get(self, layer, key):
+        """Load an artifact and increment hit or miss accounting.
+
+        Args:
+            layer (str): One of ir, feature_set, fold_transform, matrix, estimator or evaluation.
+            key (JSON-serializable object): Deterministic artifact identity within the namespace.
+
+        Returns:
+            Any or None: Cached object, or None on a miss.
+
+        Notes:
+            Does not copy in-memory objects. Corrupt disk artifacts and I/O errors propagate
+            instead of silently returning an unrelated or incomplete result.
+        """
+        path = self._path(layer, key)
+        if path is not None and path.exists():
+            self.hits += 1
+            return joblib.load(path)
+        memory_key = (layer, content_hash(key))
+        if path is None and memory_key in self.memory:
+            self.hits += 1
+            return self.memory[memory_key]
+        self.misses += 1
+        return None
+
+    def put(self, layer, key, value):
+        """Store an artifact atomically on disk or with bounded in-memory retention.
+
+        Args:
+            layer (str): One of ir, feature_set, fold_transform, matrix, estimator or evaluation.
+            key (JSON-serializable object): Deterministic artifact identity within the namespace.
+            value (Any): Trusted joblib-serializable artifact; callers treat retrieved objects as shared.
+
+        Returns:
+            None: Mutates cache storage.
+
+        Notes:
+            Disk writes use a unique sibling temporary file followed by replacement, so
+            readers never observe a partially serialized destination.
+        """
+        path = self._path(layer, key)
+        if path is None:
+            self.memory[layer, content_hash(key)] = value
+            if layer in {"matrix", "fold_transform", "estimator"}:
+                # ponytail: retain eight heavy entries per layer; use disk storage for larger searches.
+                entries = [item for item in self.memory if item[0] == layer]
+                if len(entries) > 8:
+                    del self.memory[entries[0]]
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            temporary = path.with_suffix(f".{uuid.uuid4().hex}.tmp")
+            joblib.dump(value, temporary)
+            temporary.replace(path)

featune/cli.py

@@ -0,0 +1,200 @@
+# SPDX-FileCopyrightText: 2026 Featune contributors
+# SPDX-License-Identifier: MIT
+
+"""Configuration-driven search and artifact commands.
+
+Exposes a closed configuration-driven command surface. Credentialed LLM work is
+performed only by an explicitly configured optimize command.
+
+Created:
+    2026-09-21
+"""
+
+import argparse
+import json
+import logging
+from pathlib import Path
+
+import pandas as pd
+from sklearn.ensemble import (
+    HistGradientBoostingClassifier,
+    HistGradientBoostingRegressor,
+    RandomForestClassifier,
+)
+from sklearn.linear_model import LogisticRegression, Ridge
+
+from .evaluation import CVEvaluator
+from .logging_utils import ColorFormatter
+from .samplers import AutonomousSampler, EvolutionSampler, HybridSampler, LLMSampler, RandomSampler
+from .schema import DatasetSchema
+from .study import create_study, load_study
+from .tabpfn import TabPFNClassifier, TabPFNRegressor, default_estimator
+
+
+def build_estimator(config, metric="auc", random_state=42):
+    """Instantiate an estimator from the CLI's closed model registry.
+
+    Args:
+        config (dict): type (default tabpfn) and optional params mapping.
+        metric (str): Metric identifying the task for the automatic TabPFN preset.
+        random_state (int): Seed for the default TabPFN preset.
+
+    Returns:
+        sklearn estimator: Unfitted model with the requested constructor parameters.
+
+    Raises:
+        ValueError: The estimator type is not registered.
+        ImportError: A required model dependency is missing from the installation.
+    """
+    classes = {
+        "logistic": LogisticRegression,
+        "ridge": Ridge,
+        "hist_classifier": HistGradientBoostingClassifier,
+        "hist_regressor": HistGradientBoostingRegressor,
+        "random_forest": RandomForestClassifier,
+    }
+    classes.update(tabpfn_classifier=TabPFNClassifier, tabpfn_regressor=TabPFNRegressor)
+    kind = config.get("type", "tabpfn")
+    if kind == "tabpfn":
+        return default_estimator(metric, random_state).set_params(**config.get("params", {}))
+    if kind.startswith("torch_"):
+        from .torch import TorchClassifier, TorchRegressor
+
+        classes.update(torch_classifier=TorchClassifier, torch_regressor=TorchRegressor)
+    if kind not in classes:
+        raise ValueError(f"Unknown estimator: {kind}")
+    return classes[kind](**config.get("params", {}))
+
+
+def build_sampler(config):
+    """Instantiate a configured controlled sampler while rejecting inline credentials.
+
+    Args:
+        config (dict): type plus sampler constructor settings; hybrid has llm/random sub-configs.
+
+    Returns:
+        BaseFeatureSampler: Random, evolution, LLM or hybrid policy.
+
+    Raises:
+        ValueError: The type is unknown, an API key is embedded, or sampler settings are invalid.
+
+    Notes:
+        LLM credentials must come from the environment; constructing a client does not
+        issue an HTTP request. Model generation starts only during optimize.
+    """
+    options = dict(config)
+    kind = options.pop("type", "random")
+    if "api_key" in options or "api_key" in options.get("llm", {}):
+        raise ValueError("Use FEATUNE_API_KEY instead of saving api_key in CLI configuration")
+    classes = {"random": RandomSampler, "evolution": EvolutionSampler, "llm": LLMSampler}
+    if kind == "hybrid":
+        return HybridSampler(
+            llm_sampler=LLMSampler(**options.pop("llm", {})),
+            random_sampler=EvolutionSampler(**options.pop("random", {})),
+            **options,
+        )
+    if kind == "autonomous":
+        llm = options.pop("llm", None)
+        numeric = options.pop("numeric", {})
+        if llm is not None:
+            llm.setdefault("features_per_trial", 1)
+        return AutonomousSampler(
+            llm_sampler=LLMSampler(**llm) if llm is not None else None,
+            numeric_sampler=RandomSampler(**numeric),
+            **options,
+        )
+    if kind not in classes:
+        raise ValueError(f"Unknown sampler: {kind}")
+    return classes[kind](**options)
+
+
+def main(argv=None):
+    """Dispatch configuration-driven optimization, inspection, reporting or feature export.
+
+    Args:
+        argv (sequence[str] or None): Command-line arguments; None reads sys.argv[1:].
+
+    Returns:
+        None: Writes command output and any requested artifacts.
+
+    Raises:
+        SystemExit: argparse handles help or invalid command arguments.
+
+    Notes:
+        Configuration paths resolve relative to the config file. optimize can perform
+        network requests when an LLM sampler is explicitly configured; repeated runs
+        add attempts rather than acting as idempotent queries. Errors from data loading,
+        validation, fitting and persistence propagate to the command caller.
+    """
+    parser = argparse.ArgumentParser(prog="featune", description="Semantic feature engineering search")
+    parser.add_argument("--verbose", action="store_true")
+    commands = parser.add_subparsers(dest="command", required=True)
+    optimize = commands.add_parser("optimize", help="Run or resume from a JSON configuration")
+    optimize.add_argument("config", type=Path)
+    for command in ("report", "export", "inspect"):
+        sub = commands.add_parser(command)
+        sub.add_argument("--storage", required=True)
+        sub.add_argument("--study-name", default="default")
+        if command != "inspect":
+            sub.add_argument("--output", type=Path, required=True)
+    args = parser.parse_args(argv)
+    if not logging.getLogger().handlers:
+        logging.basicConfig(level=logging.DEBUG if args.verbose else logging.INFO)
+        handler = logging.getLogger().handlers[0]
+        handler.setFormatter(
+            ColorFormatter("%(asctime)s | %(levelname)s | %(message)s", color=handler.stream.isatty())
+        )
+    if args.command == "optimize":
+        config = json.loads(args.config.read_text(encoding="utf-8"))
+        base = args.config.resolve().parent
+        dataset = config["data"]
+        path = base / dataset["path"]
+        data = pd.read_parquet(path) if path.suffix == ".parquet" else pd.read_csv(path)
+        y = data.pop(dataset["target"])
+        groups = data.pop(dataset["groups"]) if dataset.get("groups") else None
+        schema_config = config["schema"]
+        if isinstance(schema_config, str):
+            schema_config = json.loads((base / schema_config).read_text(encoding="utf-8"))
+        schema = DatasetSchema.model_validate(schema_config)
+        if dataset["target"] in schema.usable:
+            raise ValueError("Target must not be a usable schema field")
+        options = dict(config.get("study", {}))
+        sampler = build_sampler(
+            config.get(
+                "sampler", {"type": "autonomous"} if options.get("search_strategy") == "autonomous" else {}
+            )
+        )
+        options["storage"] = base / options.get("storage", "runs")
+        study = create_study(sampler=sampler, **options)
+        evaluation = dict(config.get("evaluation", {}))
+        evaluation.setdefault("metric", study.metric)
+        estimator = build_estimator(config.get("estimator", {}), evaluation["metric"], study.random_state)
+        evaluator = CVEvaluator(estimator, **evaluation)
+        study.optimize(data, y, schema, evaluator=evaluator, groups=groups, **config.get("optimize", {}))
+        destination = study.storage.directory
+        completed = any(t.state == "COMPLETE" for t in study.trials)
+        if hasattr(study, "pipeline_"):
+            study.export_pipeline(destination / "pipeline.joblib")
+        if completed:
+            study.export_features(destination / "features.json")
+        study.trials_dataframe().to_json(destination / "trials.json", orient="records", indent=2)
+        if completed and config.get("report", False):
+            study.report(destination / "report.html")
+        print(
+            json.dumps(
+                {
+                    "best_value": study.best_value if completed else None,
+                    "best_trial": study.best_trial.number if completed else None,
+                    "stop_reason": study.stop_reason,
+                    "directory": str(destination),
+                }
+            )
+        )
+    else:
+        study = load_study(args.storage, args.study_name)
+        if args.command == "report":
+            study.report(args.output)
+        elif args.command == "export":
+            study.export_features(args.output)
+        else:
+            print(study.trials_dataframe().drop(columns=["features", "hypotheses"]).to_string(index=False))