perdix 0.3.0__py3-none-any.whl

perdix/__init__.py

@@ -0,0 +1,3 @@
+"""Perdix: feature engineering workbench for tabular and time-series data."""
+
+__version__ = "0.3.0"

perdix/__main__.py

@@ -0,0 +1,3 @@
+from perdix.main import main
+
+raise SystemExit(main())

perdix/core/__init__.py

@@ -0,0 +1,6 @@
+"""Qt-free engine: steps, recipes, analysis and exporters.
+
+Everything under ``perdix.core`` runs without a display, so the CLI,
+the tests and the generated sklearn pipelines share one implementation
+with the GUI.
+"""

perdix/core/ai.py

@@ -0,0 +1,496 @@
+"""Feature proposals from Claude.
+
+We send Claude a summary of the data as the recipe leaves it (column names,
+types, roles and summary statistics of the training rows, plus your own
+description) and ask for new features, each written as one Perdix step.
+No row is sent, and nothing about the target beyond its name and kind.
+
+Every proposal is checked before it is shown: it must be one of the allowed
+steps, its parameters must validate, it must not use the target, and it
+must run on a sample of the training rows and add a column. With
+``score=True`` each surviving proposal is also scored on the held-out rows
+(perdix.core.evaluate), so its value is measured, not claimed.
+
+With ``rounds`` above one, each later round sends Claude its earlier
+proposals and what became of them: why one was dropped, or how much it
+lowered a model's validation loss on the training rows
+(perdix.core.search.Screen). Held-out scores never go back to Claude, so
+the held-out rows stay a fair test of every round's proposals.
+
+What the check cannot catch is a feature that leaks by meaning, for
+example a formula over a column recorded after the outcome. The leakage
+report still applies to the recipe you build from the proposals.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field, replace
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from perdix.core.params import Column, Columns, ParamError
+from perdix.core.recipe import Recipe, StepConfig, TrainSplit
+from perdix.core.registry import StepError, get, is_categorical, is_datetime, is_numeric
+
+DEFAULT_MODEL = "claude-opus-5-5"
+ALLOWED = ("transform.formula", "transform.math", "gen.pairwise", "gen.group_agg", "datetime.parts",
+           "ts.lag", "ts.rolling")
+TIME_STEPS = ("ts.lag", "ts.rolling")
+MAX_CATEGORIES = 8  # top values sent per categorical column
+MAX_CATEGORY_UNIQUE = 50  # columns with more distinct values send no values at all
+
+SYSTEM = (
+    "You are a feature engineering assistant inside Perdix, a desktop tool that builds features "
+    "as a recipe of steps. You see a summary of a table (no rows) and propose new features that are "
+    "likely to help a model predict the target. Each feature is exactly one Perdix step from the "
+    "allowed list, with parameters that use only existing column names. Never use the target column "
+    "as an input. Prefer features with a clear domain reason: ratios, differences, rates per unit, "
+    "group-relative values, calendar effects, lagged and smoothed history when a time column exists. "
+    "Do not repeat columns that already exist. Keep each rationale to one or two sentences."
+)
+
+SCHEMA = {
+    "type": "object",
+    "properties": {
+        "features": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "name": {"type": "string", "description": "Short name for the feature"},
+                    "key": {"type": "string", "enum": list(ALLOWED)},
+                    "params_json": {"type": "string", "description": "The step's parameters as a JSON object"},
+                    "rationale": {"type": "string"},
+                },
+                "required": ["name", "key", "params_json", "rationale"],
+                "additionalProperties": False,
+            },
+        }
+    },
+    "required": ["features"],
+    "additionalProperties": False,
+}
+
+
+class AIError(RuntimeError):
+    """The proposal request could not be made or answered; the message says why."""
+
+
+@dataclass
+class Proposal:
+    name: str
+    key: str
+    params: dict
+    rationale: str
+    error: str = ""  # why the check dropped it ("" = it passed)
+    new_columns: list[str] = field(default_factory=list)
+    gain: float | None = None  # held-out score change, when scored
+    round: int = 1  # the round that proposed it
+    train_gain: float | None = None  # boosting gain on the training rows (rounds > 1 only)
+
+    @property
+    def ok(self) -> bool:
+        return not self.error
+
+    def to_step(self) -> StepConfig:
+        return StepConfig(self.key, dict(self.params), label=self.name[:60])
+
+
+# ---------------------------------------------------------------- summary
+
+
+def _round(v: Any) -> Any:
+    if isinstance(v, (float, np.floating)):
+        v = float(v)
+        return None if not np.isfinite(v) else float(f"{v:.6g}")
+    if isinstance(v, (np.integer,)):
+        return int(v)
+    return v
+
+
+def summarize(recipe: Recipe, df: pd.DataFrame,
+              fitted: tuple[pd.DataFrame, TrainSplit] | None = None) -> tuple[dict, pd.DataFrame, pd.DataFrame]:
+    """The summary sent to Claude, the recipe's output, and its training rows.
+
+    Statistics come from the training rows only. The target appears by name
+    and kind; none of its values or statistics are included. ``fitted`` is the
+    recipe's output and training split, when already at hand."""
+    from perdix.core.analysis import infer_task
+    from perdix.core.evaluate import fit_with_split
+
+    ds = recipe.dataset
+    # The output's own split: a step that makes new rows (resampling) gives
+    # them new labels, so the split of ``df`` would pick the wrong rows.
+    out, split = fitted if fitted is not None else fit_with_split(recipe, df)
+    train = out if split.labels is None else out.loc[out.index.isin(split.labels)]
+    roles = {"target": ds.target, "time": ds.time, "group": ds.group}
+    cols = []
+    for c in train.columns:
+        if c == ds.target:
+            continue
+        s = train[c]
+        info: dict[str, Any] = {"name": str(c), "dtype": str(s.dtype),
+                                "missing_pct": _round(100.0 * s.isna().mean()) if len(s) else 0.0}
+        role = next((k for k, v in roles.items() if v and v == c), "")
+        if role:
+            info["role"] = role
+        if is_datetime(s):
+            info["kind"] = "datetime"
+            if s.notna().any():
+                info["min"], info["max"] = s.min().isoformat(), s.max().isoformat()
+        elif is_numeric(s):
+            x = pd.to_numeric(s, errors="coerce").astype(float)
+            x = x[np.isfinite(x)]
+            info["kind"] = "numeric"
+            info["distinct"] = int(x.nunique())
+            if len(x):
+                q = x.quantile([0.25, 0.5, 0.75])
+                info.update(mean=_round(x.mean()), std=_round(x.std()), min=_round(x.min()),
+                            p25=_round(q.iloc[0]), median=_round(q.iloc[1]), p75=_round(q.iloc[2]),
+                            max=_round(x.max()))
+        elif is_categorical(s):
+            vc = s.dropna().astype(str).value_counts()
+            vc = vc.iloc[np.lexsort((vc.index.to_numpy(dtype=str), -vc.to_numpy()))]  # ties by text
+            words = s.dropna().astype(str).str.split().str.len()
+            if len(vc) > MAX_CATEGORY_UNIQUE or (len(words) and words.mean() > 3):
+                info["kind"] = "text"
+                info["distinct"] = int(len(vc))
+                if len(words):
+                    info["mean_words"] = _round(words.mean())
+            else:
+                info["kind"] = "categorical"
+                info["distinct"] = int(len(vc))
+                info["top"] = {str(k): _round(100.0 * v / max(len(s.dropna()), 1))
+                               for k, v in vc.head(MAX_CATEGORIES).items()}
+        else:
+            info["kind"] = "other"
+        cols.append(info)
+    target = {}
+    if ds.target and ds.target in train.columns:
+        target = {"name": ds.target, "task": infer_task(train[ds.target].dropna())}
+    summary = {"training_rows": int(len(train)), "target": target,
+               "time": ds.time, "group": ds.group, "columns": cols}
+    return summary, out, train
+
+
+def _allowed_steps(ds) -> list[dict]:
+    keys = [k for k in ALLOWED if ds.time or k not in TIME_STEPS]
+    docs = []
+    for key in keys:
+        step = get(key)
+        params = [{"name": prm.name, "type": type(prm).__name__, "default": prm.default,
+                   **({"options": list(prm.options)} if hasattr(prm, "options") and prm.options else {}),
+                   **({"help": prm.help} if prm.help else {})}
+                  for prm in step.params]
+        docs.append({"key": key, "title": step.title, "description": step.description, "params": params})
+    return docs
+
+
+def build_prompt(summary: dict, ds, n: int, description: str) -> str:
+    rules = [
+        f"Propose at most {n} features.",
+        "Use only column names that appear in the summary; never use the target column.",
+        "params_json is a JSON object with the step's parameter names; omitted parameters take their default.",
+        "transform.formula expressions are pandas DataFrame.eval expressions: arithmetic and comparisons "
+        "over column names, with functions such as log, log1p, sqrt, exp, abs; quote names with spaces in "
+        "backticks. Give each formula a new column name in 'name'.",
+        "A Columns parameter is a JSON list of column names.",
+    ]
+    if not ds.time:
+        rules.append("There is no time column, so no time-series steps.")
+    payload = {
+        "dataset_summary": summary,
+        "user_description": description or "(none given)",
+        "allowed_steps": _allowed_steps(ds),
+        "rules": rules,
+    }
+    return json.dumps(payload, indent=1, default=str)
+
+
+def build_feedback(proposals: list[Proposal], n: int) -> str:
+    """What became of the earlier rounds' proposals, sent after the prompt in the next round."""
+    earlier = []
+    for p in proposals:
+        entry: dict[str, Any] = {"round": p.round, "name": p.name, "key": p.key, "params": p.params}
+        if not p.ok:
+            entry["outcome"] = f"dropped: {p.error}"
+        elif p.train_gain is None:
+            entry["outcome"] = "passed the checks but could not be scored"
+        else:
+            entry["outcome"] = "helps" if p.train_gain > 0 else "adds nothing"
+            entry["training_gain"] = _round(p.train_gain)
+            entry["columns"] = p.new_columns
+        earlier.append(entry)
+    rules = [
+        "These are your proposals from earlier rounds and what became of them. Each one that passed the checks "
+        "was scored on the training rows: training_gain is the share by which it lowered the validation loss of "
+        "a model that already has every column in the summary and the feature's own inputs. Above zero helps; "
+        "zero or below adds nothing.",
+        f"Propose at most {n} new features. Do not repeat an earlier proposal or reuse a column name it made.",
+        "Build on what helped (other inputs, other groupings, related forms), leave directions that added "
+        "nothing, and fix a dropped proposal only if the reason it was dropped can be fixed.",
+    ]
+    return json.dumps({"earlier_proposals": earlier, "rules": rules}, indent=1, default=str)
+
+
+# ---------------------------------------------------------------- calling Claude
+
+
+def _client(client):
+    if client is not None:
+        return client
+    try:
+        import anthropic
+    except ImportError:
+        raise AIError("AI proposals need the anthropic package: pip install 'perdix[ai]'") from None
+    try:
+        return anthropic.Anthropic()
+    except anthropic.AnthropicError as e:
+        raise AIError("no Anthropic credentials: set ANTHROPIC_API_KEY, or sign in with 'ant auth login'") from e
+
+
+def _call(client, model: str, prompt: str, feedback: str | None = None, cache: bool = False):
+    content: Any = prompt
+    if cache:
+        # Every round sends the same prompt first: cache it, and put the feedback after it.
+        content = [{"type": "text", "text": prompt, "cache_control": {"type": "ephemeral"}}]
+        if feedback:
+            content.append({"type": "text", "text": feedback})
+    kwargs = dict(
+        model=model,
+        max_tokens=16000,
+        thinking={"type": "adaptive"},
+        output_config={"effort": "high", "format": {"type": "json_schema", "schema": SCHEMA}},
+        # A declined request is re-run on Anthropic's recommended fallback model.
+        betas=["server-side-fallback-2026-07-01"],
+        fallbacks="default",
+        system=SYSTEM,
+        messages=[{"role": "user", "content": content}],
+    )
+    try:
+        import anthropic
+    except ImportError:  # a test double needs no SDK
+        return client.beta.messages.create(**kwargs)
+    try:
+        return client.beta.messages.create(**kwargs)
+    except anthropic.AuthenticationError as e:
+        raise AIError("Anthropic rejected the credentials (check ANTHROPIC_API_KEY)") from e
+    except anthropic.PermissionDeniedError as e:
+        raise AIError(f"the credentials may not use {model}") from e
+    except anthropic.NotFoundError as e:
+        raise AIError(f"model {model!r} not found") from e
+    except anthropic.RateLimitError as e:
+        raise AIError("rate limited by the Anthropic API; try again in a minute") from e
+    except anthropic.BadRequestError as e:
+        raise AIError(f"the Anthropic API refused the request: {e.message}") from e
+    except anthropic.APIStatusError as e:
+        raise AIError(f"Anthropic API error {e.status_code}; try again later") from e
+    except anthropic.APIConnectionError as e:
+        raise AIError("cannot reach the Anthropic API (network)") from e
+
+
+def _answer(response) -> list[dict]:
+    if response.stop_reason == "refusal":
+        raise AIError("Claude declined to propose features for this data")
+    if response.stop_reason == "max_tokens":
+        raise AIError("the answer was cut off; ask for fewer features")
+    text = next((b.text for b in response.content if getattr(b, "type", "") == "text"), "")
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError as e:
+        raise AIError("the answer was not valid JSON") from e
+    items = data.get("features") if isinstance(data, dict) else None
+    if not isinstance(items, list):
+        raise AIError("the answer held no feature list")
+    return [x for x in items if isinstance(x, dict)]
+
+
+# ---------------------------------------------------------------- checking
+
+
+def _uses_target(cfg: StepConfig, target: str) -> bool:
+    if not target:
+        return False
+    for spec in cfg.step.params:
+        v = cfg.params.get(spec.name)
+        if isinstance(spec, Column) and v == target:
+            return True
+        if isinstance(spec, Columns) and target in (v or []):
+            return True
+    if cfg.key == "transform.formula":
+        expr = cfg.params.get("expression", "")
+        if re.search(rf"(?<![\w`]){re.escape(target)}(?![\w`])", expr) or f"`{target}`" in expr:
+            return True
+    return False
+
+
+def check(item: dict, ds, train: pd.DataFrame, sample_rows: int = 2000, seed: int = 0) -> Proposal:
+    """Build a Proposal from one answer item, with ``error`` set if it fails a check."""
+    prop = Proposal(name=str(item.get("name", ""))[:80], key=str(item.get("key", "")), params={},
+                    rationale=str(item.get("rationale", "")))
+    try:
+        params = json.loads(item.get("params_json") or "{}")
+    except json.JSONDecodeError:
+        prop.error = "parameters are not valid JSON"
+        return prop
+    if not isinstance(params, dict):
+        prop.error = "parameters are not a JSON object"
+        return prop
+    prop.params = params
+    if prop.key not in ALLOWED:
+        prop.error = f"{prop.key!r} is not an allowed step"
+        return prop
+    if prop.key in TIME_STEPS and not ds.time:
+        prop.error = "time-series step without a time column"
+        return prop
+    if prop.key == "transform.formula" and not params.get("name"):
+        params["name"] = re.sub(r"\W+", "_", prop.name).strip("_") or "feature"
+    try:
+        cfg = StepConfig(prop.key, params)
+    except (ParamError, StepError) as e:
+        prop.error = f"invalid parameters: {e}"
+        return prop
+    prop.params = cfg.params
+    if _uses_target(cfg, ds.target):
+        prop.error = "uses the target"
+        return prop
+    sample = train if len(train) <= sample_rows else train.sample(sample_rows, random_state=seed).sort_index()
+    try:
+        out = Recipe(dataset=replace(ds, fit_fraction=1.0), steps=[cfg]).fit_transform(sample)
+    except Exception as e:  # noqa: BLE001 - any failure drops the proposal, with the reason
+        prop.error = f"does not run: {e}"
+        return prop
+    new = [c for c in out.columns if c not in sample.columns]
+    changed = [c for c in sample.columns if c in out.columns and not out[c].equals(sample[c])]
+    if not new:
+        prop.error = "adds no column" + (" (it overwrites existing ones)" if changed else "")
+        return prop
+    if all(out[c].isna().all() for c in new):
+        prop.error = "gives only missing values"
+        return prop
+    prop.new_columns = new
+    return prop
+
+
+def _scores(recipe: Recipe, df: pd.DataFrame, proposals: list[Proposal], out: pd.DataFrame,
+            split: TrainSplit) -> None:
+    """Held-out gain per passing proposal; left None if evaluation is unavailable.
+    Each proposal adds one step, so only that step is fitted on ``out``."""
+    from perdix.core.analysis import infer_task
+    from perdix.core.evaluate import append_step, holdout_score
+
+    ds = recipe.dataset
+    try:
+        task = infer_task(df[ds.target])
+        base = holdout_score(out, split, ds, task)
+    except Exception:  # noqa: BLE001 - scoring is optional
+        return
+    for p in proposals:
+        if not p.ok:
+            continue
+        try:
+            p.gain = holdout_score(*append_step(recipe, out, split, p.to_step()), ds, task) - base
+        except Exception:  # noqa: BLE001
+            p.gain = None
+
+
+def _inputs(cfg: StepConfig, columns) -> list[str]:
+    """The existing columns a step reads: names among its parameters, and in a formula."""
+    names = [str(c) for c in columns]
+    known = set(names)
+    found: list[str] = []
+    for v in cfg.params.values():
+        for x in v if isinstance(v, (list, tuple)) else [v]:
+            if isinstance(x, str) and x in known and x not in found:
+                found.append(x)
+    if cfg.key == "transform.formula":
+        expr = cfg.params.get("expression", "")
+        for c in names:
+            if c not in found and (f"`{c}`" in expr or re.search(rf"(?<![\w`]){re.escape(c)}(?![\w`])", expr)):
+                found.append(c)
+    return found
+
+
+def _repeat(p: Proposal, earlier: list[Proposal]) -> None:
+    """Drop a proposal that repeats one from an earlier round, or makes a column one of them made."""
+    if not p.ok:
+        return
+    for q in earlier:
+        if q.key == p.key and q.params == p.params:
+            p.error = f"repeats {q.name!r} from round {q.round}"
+            return
+        same = [c for c in p.new_columns if q.ok and c in q.new_columns]
+        if same:
+            p.error = f"makes column {same[0]!r}, as {q.name!r} from round {q.round} does"
+            return
+
+
+def _train_gains(recipe: Recipe, out: pd.DataFrame, split: TrainSplit, proposals: list[Proposal], screen) -> None:
+    """Boosting gain on the training rows per passing proposal; left None if it cannot be computed.
+    The step is fitted on the recipe's output as it would be in the recipe."""
+    from perdix.core.evaluate import append_step
+
+    for p in proposals:
+        if not p.ok:
+            continue
+        try:
+            cfg = p.to_step()
+            res, _ = append_step(recipe, out, split, cfg)
+            rows = res.loc[screen.index]
+            p.train_gain = float(screen.gain(rows[p.new_columns], rows[_inputs(cfg, out.columns)]))
+        except Exception:  # noqa: BLE001 - a proposal without a gain still goes back, as unscored
+            p.train_gain = None
+
+
+def propose(recipe: Recipe, df: pd.DataFrame, *, n: int = 8, description: str = "", model: str | None = None,
+            client=None, score: bool = False, sample_rows: int = 2000, rounds: int = 1, seed: int = 0,
+            fitted: tuple[pd.DataFrame, TrainSplit] | None = None) -> list[Proposal]:
+    """Ask Claude for up to ``n`` features per round, checked; passing proposals come first.
+
+    Each round after the first sends what became of the earlier proposals
+    (``build_feedback``): Claude can build on what helped and leave what did
+    not. That needs a target, since the feedback is a gain on the training rows."""
+    if n < 1:
+        raise ValueError("ask for at least one feature")
+    if rounds < 1:
+        raise ValueError("run at least one round")
+    ds = recipe.dataset
+    if rounds > 1 and (not ds.target or ds.target not in df.columns):
+        raise ValueError("more than one round needs a target column (set it under Dataset): the feedback is "
+                         "each feature's gain on the training rows")
+    from perdix.core.evaluate import fit_with_split
+
+    out, split = fitted if fitted is not None else fit_with_split(recipe, df)
+    summary, out, train = summarize(recipe, df, (out, split))
+    prompt = build_prompt(summary, ds, n, description)
+    client = _client(client)
+    screen = None
+    if rounds > 1:
+        from perdix.core.analysis import infer_task
+        from perdix.core.search import Screen, training_sample
+
+        screen = Screen(training_sample(train, ds.target, 20000, seed), ds.context(), infer_task(df[ds.target]),
+                        seed=seed, groups=ds.group if ds.split == "group" else "")
+    proposals: list[Proposal] = []
+    for r in range(1, rounds + 1):
+        feedback = build_feedback(proposals, n) if proposals else None
+        items = _answer(_call(client, model or DEFAULT_MODEL, prompt, feedback, cache=rounds > 1))[:n]
+        batch = [check(it, ds, train, sample_rows) for it in items]
+        for p in batch:
+            p.round = r
+            _repeat(p, proposals)
+        if screen is not None:
+            _train_gains(recipe, out, split, batch, screen)
+        proposals += batch
+    if score:
+        _scores(recipe, df, proposals, out, split)
+
+    def rank(p: Proposal):
+        g = p.gain if p.gain is not None else p.train_gain
+        return (not p.ok, -(g or 0.0))
+
+    return sorted(proposals, key=rank)