Cost estimation

concrete_fhe_toolkit.ml.estimation

Static cost estimation for FHE models — before compiling anything.

Answers "how expensive will this model be?" from the model's public structure and the feature bounds alone: it counts the encrypted operations the circuit will contain (comparisons, table lookups, multiplications) and the widest lookup domain, then maps them to the same qualitative levels the lookup guardrails use. Estimates are structural, not wall-clock promises — use them to compare models and to catch circuits that will not fit before paying for a compile.

ModelCostEstimate dataclass

Structural cost summary for one model at given feature bounds.

Attributes:

Name	Type	Description
comparisons	int	Encrypted comparison operations (each becomes a TLU).
lookups	int	Explicit table lookups (argmin/argmax encodings included).
multiplications	int	Encrypted multiplications.
max_lookup_input_bits	int	Widest lookup-domain bit width in the circuit — the main driver of key size and runtime.
level	str	small / moderate / large / very-large, aligned with the estimate_lookup_cost guardrail levels.
notes	List[str]	Human-readable advisories (for example when an argmin encoding approaches Concrete's practical bit-width limits).

Source code in src/concrete_fhe_toolkit/ml/estimation.py

@dataclass
class ModelCostEstimate:
    """Structural cost summary for one model at given feature bounds.

    Attributes:
        comparisons: Encrypted comparison operations (each becomes a TLU).
        lookups: Explicit table lookups (argmin/argmax encodings included).
        multiplications: Encrypted multiplications.
        max_lookup_input_bits: Widest lookup-domain bit width in the
            circuit — the main driver of key size and runtime.
        level: ``small`` / ``moderate`` / ``large`` / ``very-large``,
            aligned with the ``estimate_lookup_cost`` guardrail levels.
        notes: Human-readable advisories (for example when an argmin
            encoding approaches Concrete's practical bit-width limits).
    """

    comparisons: int = 0
    lookups: int = 0
    multiplications: int = 0
    max_lookup_input_bits: int = 0
    level: str = "small"
    notes: List[str] = field(default_factory=list)

estimate_model_cost

estimate_model_cost(model: Any, *, min_feature: int, max_feature: int) -> ModelCostEstimate

[Client-Side Helper] Estimate a model's encrypted-operation footprint before compiling.

Parameters:

Name	Type	Description	Default
model	Any	Any toolkit model instance (FHEModel subclasses, including pipelines — steps are summed).	required
min_feature	int	Inclusive lower bound of the encrypted features the model will see.	required
max_feature	int	Inclusive upper bound of those features.	required

Returns:

Name	Type	Description
A	ModelCostEstimate	class:ModelCostEstimate with operation counts and a
	ModelCostEstimate	qualitative level.

Example

from concrete_fhe_toolkit.ml import FHEKNN
from concrete_fhe_toolkit.ml.estimation import estimate_model_cost

model = FHEKNN(X_train, y_train, k=3)
report = estimate_model_cost(model, min_feature=0, max_feature=15)
print(report.level, report.max_lookup_input_bits, *report.notes)

Source code in src/concrete_fhe_toolkit/ml/estimation.py

@client_side_helper
def estimate_model_cost(
    model: Any,
    *,
    min_feature: int,
    max_feature: int,
) -> ModelCostEstimate:
    """[Client-Side Helper] Estimate a model's encrypted-operation footprint before compiling.

    Args:
        model: Any toolkit model instance (``FHEModel`` subclasses,
            including pipelines — steps are summed).
        min_feature: Inclusive lower bound of the encrypted features the
            model will see.
        max_feature: Inclusive upper bound of those features.

    Returns:
        A :class:`ModelCostEstimate` with operation counts and a
        qualitative level.

    Example:
        ```python
        from concrete_fhe_toolkit.ml import FHEKNN
        from concrete_fhe_toolkit.ml.estimation import estimate_model_cost

        model = FHEKNN(X_train, y_train, k=3)
        report = estimate_model_cost(model, min_feature=0, max_feature=15)
        print(report.level, report.max_lookup_input_bits, *report.notes)
        ```
    """
    minimum, maximum = validate_bounds(min_feature, max_feature)
    span = maximum - minimum
    estimate = ModelCostEstimate()
    _accumulate(model, estimate, span)

    bits = estimate.max_lookup_input_bits
    if bits >= 16:
        estimate.level = "very-large"
        estimate.notes.append(
            f"a lookup needs {bits}-bit inputs — likely beyond Concrete's "
            "practical parameter space; shrink bounds or sizes"
        )
    elif bits >= 10 or estimate.lookups + estimate.comparisons >= 200:
        estimate.level = "very-large"
    elif bits >= 8 or estimate.lookups + estimate.comparisons >= 60:
        estimate.level = "large"
    elif bits >= 7 or estimate.lookups + estimate.comparisons >= 20:
        estimate.level = "moderate"
    else:
        estimate.level = "small"
    return estimate