Encoder Selection

Start with Kumo’s inferred encoders. Override a column only when it needs a specific transformation or feature representation. First check each column’s semantic type (stype): an integer category needs "categorical", not "numerical". Kumo selects encoders from semantic types and column statistics, so an explicit constructor can replace a useful inferred configuration. An override changes the encoding, not the semantic type or the graph’s relationships. Set column types when preparing Tables, then follow Graphs to connect the tables and create a snapshot. Apply optional encoder overrides through plan.column_processing before training. The examples below assume you have created a plan as shown in the Model Plan Guide.

Supported Encoders

Import encoders from kumoapi.encoder and Stype from kumoapi.typing.

ID is uppercase. Compatible encoders for each type are listed above; Null is also available for every type. Constructor defaults in the tables below describe explicit instances, not the configuration Kumo will infer.

Null() excludes a feature; it does not remove a primary key or foreign key relationship from the graph. Image encoding is not part of this guide’s supported input types.

Numerical Encoders

The logarithmic encoders compress a long tail on the corresponding side of the distribution. They do not accept a scaler argument. The legacy "raise" missing-value setting is retained for compatibility and should not be used in new plans.

Categorical and ID Encoders

Index assigns retained categories their own learned representations. Hash bounds the number of distinct representations, so different values can share a bucket. The model architecture’s channel count controls the representation size. Hash does not accept min_occ or na_strategy="zero".

For a categorical products.brand column, this example caps hashing at 4096 buckets; that count is illustrative, not an inferred or optimal value:

from kumoapi.encoder import Hash
plan.column_processing.encoder_overrides = {
    **(plan.column_processing.encoder_overrides or {}),
    "products.brand": Hash(num_components=4096),
}

Multicategorical Encoder

Kumo processes each category in the value and combines the results. The separator is inferred from column statistics; MultiCategorical does not accept a sep argument.

Sequence and Embedding Encoder

Use NumericalList for stype="sequence", including vectors computed outside Kumo.

These scaler choices differ from Numerical: "minmax" and "robust" are not sequence scaler options.

Timestamp Encoder

Datetime extracts calendar features from stype="timestamp" columns.

Text Encoder

Use TextEmbedding for columns with stype="text", such as product descriptions and reviews. It looks up pretrained vectors for recognized words in each cell and averages them into a feature vector. Unknown words are ignored; missing cells and cells with no recognized words produce a zero vector.

Text Embedding Models

The default model is GloVe 6B with 50 dimensions. Add its vector package to the Python environment where Kumo Engine runs:

pip install "kumo-engine[text]"

Use the package index configured during environment setup. That index must provide compatible builds of both Kumo Engine and its optional kumo-glove-6b-50d dependency. Kumo Engine does not download word vectors during training.

Automatic encoder selection can choose Null() to exclude text columns whose values are too short or contain too few recognized words. To encode products.description explicitly, merge a text override into your plan before constructing the trainer:

from kumo.engine import Trainer
from kumoapi.encoder import TextEmbedding
plan.column_processing.encoder_overrides = {
    **(plan.column_processing.encoder_overrides or {}),
    "products.description": TextEmbedding(),
}
trainer = Trainer(plan)

Replace products.description with a text column in your graph. If training reports a missing embedding model, install its vector package or register it as shown below. To exclude the column instead, use Null() in its encoder override. Only columns that use TextEmbedding require word vectors.

Use Another GloVe Model

Use another vector vocabulary when it better matches your text; retain the default when you have no specific alternative to evaluate.

from kumo.engine import EmbeddingModelStore, GloVeVectors, Trainer
from kumoapi.encoder import TextEmbedding
store = EmbeddingModelStore()
store.add("descriptions", GloVeVectors("/path/to/glove.42B.300d.zip"))
plan.column_processing.encoder_overrides = {
    **(plan.column_processing.encoder_overrides or {}),
    "products.description": TextEmbedding(model="descriptions"),
}
trainer = Trainer(plan, embedding_models=store)

Reload a Trained Text Model

A saved model still needs the word vectors used during training. For the default model, keep the text package installed in the prediction environment. For a registered model, recreate the store with the same vectors and pass it when loading:

trainer = Trainer.load(bundle_dir, embedding_models=store)

Replace bundle_dir with your saved model bundle directory. Kumo matches the vectors by model identity, so the registration name can change but the vectors and tokenization must match.

Custom Word Vectors

Use custom vectors when you already have a vocabulary and embeddings suited to your text. Keep an installed model when you do not need a custom vocabulary or tokenizer.

"""Tiny illustrative vectors. This is not a pretrained language model."""
import hashlib
import json
import numpy as np
import pandas as pd
class ExampleVectors:
    family = "example-words/1"
    dim = 2
    label = "Two illustrative word vectors"
    tokenizer_version = "lower-whitespace-drop-unknown/1"
    def vocabulary(self):
        return pd.Index(["red", "shoe"])
    def vectors(self):
        return np.array([[1.0, 0.0], [0.0, 1.0]], dtype=np.float32)
    def tokenize(self, texts):
        lookup = {word: row for row, word in enumerate(self.vocabulary())}
        rowptr, rows = [0], []
        for text in texts:
            if isinstance(text, str):
                rows.extend(lookup[word] for word in text.lower().split()
                            if word in lookup)
            rowptr.append(len(rows))
        return np.array(rowptr, dtype=np.int64), np.array(rows, dtype=np.int64)
    def fingerprint(self):
        metadata = json.dumps([self.tokenizer_version,
                               self.vocabulary().tolist()]).encode("utf-8")
        return hashlib.sha256(metadata + self.vectors().astype("<f4").tobytes()).hexdigest()

from kumo.engine import EmbeddingModelStore, Trainer
from kumoapi.encoder import TextEmbedding
from example_vectors import ExampleVectors
store = EmbeddingModelStore()
store.add("example", ExampleVectors())
plan.column_processing.encoder_overrides = {
    **(plan.column_processing.encoder_overrides or {}),
    "products.description": TextEmbedding(model="example"),
}
trainer = Trainer(plan, embedding_models=store)

Encoder Overrides

Set encoder_overrides to a dictionary of case-sensitive "table.column" names and encoder instances. Use the table names in your graph, not a warehouse’s fully qualified table path. Leave it as None to retain inferred encoders.

For a graph containing products.price, products.category, and products.description, with semantic types numerical, categorical, and text respectively:

from kumoapi.encoder import Index, Null, Numerical
plan.column_processing.encoder_overrides = {
    "products.price": Numerical(scaler="minmax", na_strategy="zero"),
    "products.category": Index(min_occ=2),
    "products.description": Null(),
}

This scales prices, imputes missing prices with zero, groups rare categories as missing, and excludes descriptions from input features. Assigning this dictionary replaces any earlier encoder overrides. To retain earlier overrides, merge them into the new dictionary.

Transform a Regression Target

Use the special key "train_table.TARGET" to override the generated target encoder. This controls the value the model learns to predict, rather than an input feature such as products.price. For a scalar numerical regression target with a long upper tail:

from kumoapi.encoder import MaxLogNumerical
plan.column_processing.encoder_overrides = {
    **(plan.column_processing.encoder_overrides or {}),
    "train_table.TARGET": MaxLogNumerical(),
}

Pass this plan to Trainer before fitting your regression training table. The transform uses log(x - min + 1), where min comes from the target statistics. Values below that fitted minimum are clamped to the same transformed value as the minimum, so decoding cannot recover those lower values. Kumo reverses the target transform when producing regression predictions, so TARGET_PRED is in the original target units. Do not exponentiate it again. Keep the saved model’s target encoder when reloading. This example does not apply to categorical, list, or forecasting targets, and a logarithmic transform does not guarantee better predictions.

Missing Values

Set plan.column_processing.na_strategy to choose missing-value defaults by semantic type. Kumo applies each default to compatible inferred feature encoders of that type. Leave a type out of the dictionary to keep its inferred strategy. Use encoder_overrides for column-specific exceptions.

Before constructing Trainer(plan), this example sets numerical features to zero imputation while using mean imputation for products.price:

from kumoapi.encoder import Numerical
from kumoapi.typing import Stype
plan.column_processing.na_strategy = {Stype.numerical: "zero"}
plan.column_processing.encoder_overrides = {
    **(plan.column_processing.encoder_overrides or {}),
    "products.price": Numerical(na_strategy="mean"),
}

Replace products.price with a numerical column in your graph. The dictionary merge preserves other encoder overrides; the na_strategy assignment replaces any earlier type-wide defaults. Choose strategies supported by the semantic type and encoder:

Precedence

A per-column override replaces the inferred encoder, including its missing-value configuration. The type-wide default does not apply to a column with an explicit override. If you omit na_strategy from an explicit Numerical() instance, it uses "mean" even when the type-wide numerical default is "zero".

A warm start reuses the source checkpoint’s fitted encoders ahead of both settings. Changing the destination plan’s missing-value defaults or overrides does not replace those fitted encoders. Use a fresh training run to fit different encoders.

Unsupported Strategies

An invalid type/strategy combination, such as "most_frequent" for Stype.numerical, fails model plan validation. Assignment to the public plan alone does not establish that the combination is valid. Use the supported values in the encoder tables above.

A strategy can be valid for a semantic type but unsupported by a particular inferred encoder. For example, Stype.categorical: "zero" works with Index, but an inferred Hash encoder keeps its default strategy and emits a warning naming the column and allowed strategies. Choose one of those strategies or use a compatible explicit encoder override. Encoders without a missing-value option, such as Null, are left unchanged without this warning.

Check Your Configuration

Inspect plan.as_json() before passing the plan to Trainer. Encoder constructors reject unsupported arguments and invalid option values. During plan validation, Kumo checks that override columns exist and that each encoder supports the column’s semantic type. If it reports an invalid column name, use the case-sensitive table and column names in the graph. If it reports an incompatible encoder, correct the semantic type or select a compatible encoder from the table above. For a missing text model, install the text extra, register the required model, or exclude the affected text column with Null().

When your graph snapshot and plan are ready, follow Training to fit the model. Return to the Model Plan Guide for architecture and optimization settings.