kalfa 3.0.0.dev0__py3-none-any.whl

kalfa/commands/guide/about.py

@@ -0,0 +1,93 @@
+from kalfa.commands.guide.words import and_list
+from kalfa.core.build import TOP_LEVEL
+
+
+RUN = "run"
+RUN_KEYS = ("seed", "device", "record", "include", "plugins")
+UNKNOWN_COLOR = "grey35"
+
+COLORS = {"run": "blue_violet", "params": "dark_magenta", "data": "dark_cyan", "models": "dodger_blue3",
+          "losses": "red3", "metrics": "dark_orange3", "optimizers": "green4", "train": "dark_goldenrod",
+          "rules": "deep_pink4", "plots": "turquoise4", "generate": "medium_purple4", "sweep": "chartreuse4"}
+
+ABOUT = {
+    "run": ("Top level values that set up the run as a whole. seed seeds every random stream and the splits (0 when "
+            "it is not written). device is auto (cuda, then mps, then cpu), cpu, mps, cuda or cuda:<index>. record "
+            "is the directory the run writes, new or empty; without it a run writes runs/<config name>_<datetime>. "
+            "include merges other files below this one, and plugins are modules imported before the build so that "
+            "the short names they register can be used."),
+    "params": ("Values the rest of the config reads as $name$. They are substituted after every layer is merged: a "
+               "string that is only $name$ takes the value with its type, and inside a longer string the value is "
+               "written as text. The flag -p name=value overrides a param from the command line, a sweep varies them "
+               "point by point, and a param that nothing reads is a warning."),
+    "data": ("One call: the data class. It reads the files, cuts them into the train, valid and test sets, fits what "
+             "it learns (preprocessors, a vocabulary) on the train set only and yields the batches. Its batch fields "
+             "are what a model takes as inputs and what a loss or a metric names as target, and the values it "
+             "exposes once fitted are read elsewhere as @data.<name>. A relative path is looked for in the working "
+             "directory, then next to the config files."),
+    "models": ("Each name is a call of an nn.Module. kalfa calls it with the batch fields of inputs (default the "
+               "inputs of the data class, x for a table) and names what it returns after outputs (default the model "
+               "name); these names are what pred refers to. The slot keys inputs, outputs, init, weights, freeze and "
+               "ema are read by kalfa and never reach the class; init, weights, freeze and ema apply in that order. "
+               "With one model, that model is the predicts model whose outputs fill the predictions table."),
+    "losses": ("Each name is a call of a loss. A criterion compares one prediction with one target, (pred, target), "
+               "and kalfa picks the two tensors; an objective reads the outputs, the batch and the run context "
+               "itself. Every loss writes the series <set>/<name> on the sets it runs on, such as train/mse and "
+               "val/mse. A loss that an optimizer minimizes gives the gradients; the others are computed without "
+               "gradients and only observe. sample_weight names a row weight of the data (data.weights) that "
+               "multiplies the loss of every row of a criterion."),
+    "metrics": ("Each name is a call of a metric, accumulated over a whole set and written as <set>/<name>, such as "
+                "val/rmse. A metric takes the same pred, target, on, every and rescale keys as a loss. rescale is on "
+                "by default when the target has an invertible preprocessor, so the metric speaks the original units. "
+                "A loss and a metric of the same name write the same series."),
+    "optimizers": ("Each name is a call of a torch optimizer (adam, adamw, sgd or an import path). over names the "
+                   "parameters it steps, minimizes names the loss it steps on, and schedule multiplies the base lr "
+                   "after every update. The history writes lr/<name> and minimizes/<name>. A rule may patch the "
+                   "torch params and minimizes while the run goes on; over and schedule stay fixed."),
+    "train": ("The budget and the shape of the training. epochs (turns that each pass over the train set) or updates "
+              "({total, turn}) is required, never both. step is the algorithm that trains a turn (supervised when it "
+              "is not written), predicts the model whose outputs fill the predictions table, evaluate the sets "
+              "evaluated after every turn (the existing valid and test sets when it is not written), checkpoint and "
+              "report the weights kept and used at the end, track the values written as series and log the loggers."),
+    "rules": ("Each name is a rule, asked after every turn in the order of the config, after the evaluation and "
+              "before the checkpoints. A rule fires when its trigger (when) fires, and with after only from the turn "
+              "after the named rule fired; without when it fires as soon as it is ready. It fires once unless once "
+              "is false. Its effects are set (patches of plan paths, applied to the live objects), stop (the run "
+              "ends after the turn) and run (an action)."),
+    "plots": ("Each name is a call of a plot. Plots are drawn at the end of a run into <record>/plots from the "
+              "record files, and again at any time with kalfa plots RECORD. A std plot saves its image under its own "
+              "name, such as loss_curve.png; a plot of your own that returns its figure is saved under its key here."),
+    "generate": ("One call: the sampler. At the end of a run it draws n samples into <record>/samples/samples.pt, "
+                 "with a png grid for images and a txt for text; kalfa generate RECORD draws more later, and the "
+                 "write_samples action uses it from a rule when it names no sampler."),
+    "sweep": ("A sweep runs this config once per point, each point with other values of some params. strategy picks "
+              "the points, space gives the values of every swept param, objective ranks the points and record is the "
+              "sweep root whose numbered directories 0000, 0001 and so on hold the point records. kalfa sweep reads "
+              "this section."),
+}
+
+UNKNOWN_ABOUT = ("kalfa does not know the top level key {name}, so check reports it as unknown_section. The top "
+                 "level keys are {keys}.")
+
+DATA_KEYS = {
+    "file": ("the file to read; a relative path is looked for in the working directory, then next to the config "
+             "files"),
+    "folder": "the folder to read; every subdirectory is a class",
+    "split": "how the rows are cut into the train, valid and test sets: a list of ratios or a split call",
+    "batch": "the batch size, or a mapping of size, eval_size, workers, drop_last and shuffle",
+    "features": "a mapping of column patterns to preprocessors",
+    "targets": "a mapping of target columns to preprocessors",
+    "transform": "a list of image transforms applied to every set",
+    "train_transform": "a list of image transforms that replaces transform for the train set",
+}
+
+RUN_NOTES = {
+    "seed": "seeds every random stream (noise, samples, loader) and the splits",
+    "record": "the record directory the run writes; it must be new or empty, and every tool reads it afterwards",
+}
+
+
+def about_of(name):
+    if name in ABOUT:
+        return ABOUT[name]
+    return UNKNOWN_ABOUT.format(name=name, keys=and_list(TOP_LEVEL))

kalfa/commands/guide/calls.py

@@ -0,0 +1,102 @@
+import inspect
+
+from kalfa.commands.guide.words import flat, lower_first, short, unique
+from kalfa.core import aliases
+
+
+LEGO_KEYS = ("activation", "init", "schedule", "step", "strategy", "tokenizer", "when", "feed", "run", "log", "layers",
+             "each", "split", "transform", "train_transform", "sampler")
+COLUMNS = ("features", "targets")
+
+
+def use_of(value):
+    if isinstance(value, str) and value and not value.startswith(("@", "$")):
+        return value
+    if isinstance(value, dict) and isinstance(value.get("use"), str):
+        return value["use"]
+    return None
+
+
+def lego_name(text):
+    return aliases.entry_of(text) is not None or aliases.is_import_path(text)
+
+
+def legos_in(value, lego=False):
+    found = []
+    if isinstance(value, dict):
+        use = value.get("use")
+        if isinstance(use, str):
+            found.append(use)
+        for key, item in value.items():
+            if key != "use":
+                found += legos_in(item, key in LEGO_KEYS or (lego and not isinstance(use, str)))
+    elif isinstance(value, list):
+        for item in value:
+            found += legos_in(item, lego)
+    elif lego and isinstance(value, str) and lego_name(value):
+        found.append(value)
+    return found
+
+
+def first_line(target):
+    own = target.__dict__.get("__doc__") if inspect.isclass(target) else getattr(target, "__doc__", None)
+    sentence = flat(own if isinstance(own, str) else "").split(". ")[0].rstrip(".")
+    if not sentence or len(sentence) > 140 or "`" in sentence or ":math:" in sentence:
+        return None
+    return lower_first(sentence)
+
+
+def import_note(use, target):
+    if target is None:
+        return f"{use}: an import path"
+    kind = "class" if inspect.isclass(target) else "function" if inspect.isroutine(target) else "object"
+    name = getattr(target, "__name__", None) or type(target).__name__
+    line = first_line(target) if kind != "object" else None
+    return f"{use}: an import path to the {kind} {name}" + (f"; {line}" if line else "")
+
+
+def named_for(use):
+    if not aliases.is_import_path(use):
+        return None
+    found = [entry for entry in aliases.ALIASES.values() if aliases.target_path(entry.target) == use]
+    found.sort(key=lambda entry: entry.plugin)
+    return found[0] if found else None
+
+
+def known(use):
+    return aliases.entry_of(use) or named_for(use)
+
+
+def lego_note(use, target=None):
+    entry = aliases.entry_of(use)
+    if entry is not None:
+        doc = lower_first(short(entry.doc))
+        if doc and doc.lower() != use.lower():
+            return f"{use}: {doc}"
+        return f"{use} is {aliases.target_path(entry.target)}"
+    twin = named_for(use)
+    if twin is not None:
+        doc = lower_first(short(twin.doc))
+        return f"{use}: the target of the short name {twin.name}" + (f", {doc}" if doc else "")
+    if aliases.is_import_path(use):
+        return import_note(use, target)
+    return f"{use} is not a short name kalfa knows"
+
+
+def param_lines(use, value, skip=(), lead=""):
+    entry = known(use) if use else None
+    if entry is None or not isinstance(value, dict):
+        return []
+    return [f"{lead}{key}: {short(entry.params[key])}" for key in value
+            if key != "use" and key not in skip and key in entry.params]
+
+
+def call_notes(seen, path, value, skip=()):
+    use = use_of(value)
+    if use is None:
+        return []
+    notes = [lego_note(use, seen.target(path))] + param_lines(use, value, skip)
+    inner = value.items() if isinstance(value, dict) else ()
+    nested = [name for key, item in inner if key != "use" and key not in skip
+              for name in legos_in(item, key in LEGO_KEYS)]
+    return notes + [lego_note(name, seen.found(name)) for name in unique(nested) if name != use]

kalfa/commands/guide/sections.py

@@ -0,0 +1,186 @@
+from kalfa.commands.guide.about import DATA_KEYS, RUN_NOTES
+from kalfa.commands.guide.calls import COLUMNS, LEGO_KEYS, call_notes, lego_note, legos_in, param_lines, use_of
+from kalfa.commands.guide.seen import (layer_notes, override_notes, param_value_notes, patch_notes, ref_meaning,
+                                       ref_name, refs_of, swept)
+from kalfa.commands.guide.words import and_list, short, unique, value_text
+from kalfa.core import aliases
+from kalfa.core.build import SLOT_KEYS
+from kalfa.core.plan import sets_of
+
+
+QUIET_KEYS = {"optimizers": ("over", "minimizes"), "rules": ("set",)}
+PREDICTS = "its outputs fill the predictions table"
+UNTABLED = "the step computes its outputs for every batch, and this data class writes no predictions table"
+
+
+def series_note(seen, section, path):
+    node = seen.node(path) if section in ("losses", "metrics", "optimizers") else None
+    if node is None:
+        return []
+    if section == "optimizers":
+        return [f"series lr/{node.name} and minimizes/{node.name}"]
+    series = [f"{prefix}/{node.name}" for prefix in sets_of(node)]
+    series = ([f"train/{node.name}"] if section == "losses" else []) + series
+    return [f"series {and_list(unique(series))}"]
+
+
+def common_notes(seen, section, value, path, keys):
+    hidden = QUIET_KEYS.get(section, ())
+    shown = {key: item for key, item in value.items() if key not in hidden} if isinstance(value, dict) else value
+    shown = None if path == "train.predicts" else shown
+    notes = [f"{text} is {ref_meaning(text)}" for text in unique(text for _, text in refs_of(shown))]
+    notes += param_value_notes(seen, value)
+    readers = seen.readers(path) if section in ("models", "losses", "metrics") else []
+    notes += [f"read as @{path} by {and_list(readers)}"] if readers else []
+    notes += patch_notes(seen, path) if section not in ("optimizers", "rules") else []
+    notes += series_note(seen, section, path)
+    return notes + layer_notes(seen, keys, value) + override_notes(seen, path)
+
+
+def run_notes(seen, key, value, keys, path):
+    if key == "device":
+        device = seen.value("device")
+        if device in (None, "auto"):
+            return ["auto takes cuda when it is there, then mps, then cpu"]
+        return [f"the run trains on {value_text(device)}"]
+    if key == "include":
+        return ["merges these files below this one, so a key written here wins over theirs"]
+    if key == "plugins":
+        modules = getattr(seen.config, "plugins", None) or []
+        return [f"imported before the build: {and_list(modules)}; the names they register with kalfa.lego become "
+                "short names"]
+    return [RUN_NOTES[key]] if key in RUN_NOTES else []
+
+
+def param_notes(seen, key, value, keys, path):
+    paths = seen.uses.get(str(key), [])
+    if paths:
+        shown = paths[:5] + ([f"{len(paths) - 5} more"] if len(paths) > 5 else [])
+        notes = [f"read as ${key}$ by {and_list(shown)}"]
+    else:
+        notes = [f"nothing reads ${key}$"]
+    sweep = swept(seen, str(key))
+    return notes + ([sweep] if sweep else [])
+
+
+def split_text(ratios):
+    if not ratios or not all(isinstance(ratio, (int, float)) and not isinstance(ratio, bool) for ratio in ratios):
+        return None
+    names = ("train", "valid", "test")
+    shares = [f"{ratio * 100:g}% {name}" for name, ratio in zip(names, ratios) if ratio]
+    missing = [name for index, name in enumerate(names) if index >= len(ratios) or not ratios[index]]
+    tail = f", with no {and_list(missing)} set" if missing else ""
+    return f"a shuffled split: {and_list(shares)}{tail}, seeded by the top level seed"
+
+
+def target_notes(targets):
+    notes = []
+    for name, chain in (targets or {}).items():
+        chain = chain if isinstance(chain, list) else [chain]
+        names = [use_of(item) for item in chain if item is not None]
+        if not names:
+            notes.append(f"{name} is kept raw")
+        elif "label" in names:
+            notes.append(f"{name} is a classification target: label gives int64 class codes")
+        else:
+            notes.append(f"{name} is preprocessed; predictions and rescaled metrics come back in its original units")
+    return notes
+
+
+def data_notes(seen, key, value, keys, path):
+    if path == "data":
+        return call_notes(seen, "data", value)
+    target = seen.target("data")
+    if key == "use":
+        notes = [lego_note(value, target)]
+        inputs = getattr(target, "inputs", None)
+        exposes = getattr(target, "exposes", None)
+        if inputs:
+            notes.append(f"a model takes {and_list(inputs)} as inputs when it names no inputs")
+        if exposes:
+            notes.append(f"@data reads {and_list(exposes)} once it is fitted")
+        return notes
+    use = use_of(seen.mapping("data"))
+    entry = aliases.entry_of(use) if use else None
+    note = (entry.params.get(key) if entry is not None else None) or DATA_KEYS.get(key)
+    notes = [f"{key}: {short(note)}"] if note else []
+    resolved = seen.value(*keys)
+    if key == "split" and isinstance(resolved, list):
+        notes.append(split_text(resolved))
+    if key == "targets" and isinstance(resolved, dict):
+        notes += target_notes(resolved)
+    names = unique(legos_in(value, key in LEGO_KEYS or key in COLUMNS))
+    inner = use_of(value) if key in LEGO_KEYS and isinstance(value, dict) else None
+    if inner:
+        notes += [lego_note(inner)] + param_lines(inner, value)
+    return notes + [lego_note(name, seen.found(name)) for name in names if name != inner]
+
+
+def model_key_notes(name, keys):
+    notes = []
+    inputs, outputs = keys.get("inputs"), keys.get("outputs")
+    if inputs is not None:
+        listed = inputs if isinstance(inputs, list) else [inputs]
+        notes.append(f"inputs: called with the batch fields {and_list(listed)} in this order")
+    if outputs is not None:
+        listed = outputs if isinstance(outputs, list) else [outputs]
+        notes.append(f"outputs: names what it returns {and_list(listed)}; a tensor takes the first name and a tuple "
+                     "matches them in order")
+    else:
+        notes.append(f"without outputs, a tensor it returns is named {name}")
+    ema = keys.get("ema")
+    if ema is not None and ema is not False:
+        decay = ema.get("decay") if isinstance(ema, dict) else ema
+        every = ema.get("every") if isinstance(ema, dict) else None
+        text = "ema: keeps an exponential moving average copy"
+        text += f" with decay {value_text(decay)}" if decay is not None and decay is not True else ""
+        text += f", updated every {value_text(every)} steps" if every else ""
+        notes.append(text + f", read as @models.{name}.ema")
+    freeze = keys.get("freeze")
+    if freeze is True:
+        notes.append("freeze: every parameter is frozen and the module stays in eval mode")
+    elif freeze is False:
+        notes.append("freeze: false, nothing is frozen; a rule may patch it")
+    elif isinstance(freeze, (list, str)):
+        listed = freeze if isinstance(freeze, list) else [freeze]
+        notes.append(f"freeze: the parameters matching {and_list(listed)} are frozen")
+    weights = keys.get("weights")
+    if isinstance(weights, dict):
+        source = f" from the record {weights['run']}" if weights.get("run") else ""
+        notes.append(f"weights: loads the {weights.get('which') or 'last'} checkpoint of the model "
+                     f"{weights.get('model') or name}{source}")
+    elif isinstance(weights, str):
+        notes.append(f"weights: loads the last checkpoint of the model {name} from the record {weights}")
+    init = use_of(keys.get("init"))
+    if init:
+        notes += [f"init: applies {init} to the module once it is built", lego_note(init)]
+        notes += param_lines(init, keys.get("init"), lead="init.")
+    return notes
+
+
+def model_notes(seen, key, value, keys, path):
+    name = str(key)
+    notes = call_notes(seen, path, value, SLOT_KEYS["model"])
+    notes += model_key_notes(name, seen.mapping(*keys))
+    if seen.predicts() == name:
+        written = seen.mapping("train").get("predicts") is not None
+        how = "train.predicts names it" if written else "the only model, so it is the predicts model"
+        notes.append(f"{how}: {PREDICTS if seen.tabled() else UNTABLED}")
+    steppers = [opt for opt, item in seen.mapping("optimizers").items()
+                if isinstance(item, dict) and name in over_models(item.get("over"))]
+    if steppers:
+        notes.append(f"{and_list(steppers)} {'steps' if len(steppers) == 1 else 'step'} its parameters")
+    elif seen.mapping("optimizers"):
+        notes.append("no optimizer names it in over")
+    return notes
+
+
+def over_models(over):
+    items = over if isinstance(over, list) else [over]
+    found = []
+    for item in items:
+        ref = item.get("of") if isinstance(item, dict) else item
+        name = ref_name(ref, "models")
+        if name:
+            found.append(name)
+    return found