Skip to content

Normalization API

LLM-based normalization engine for tabular data.

NormalizationEngine

scinr.newton.tabular.normalization.engine.NormalizationEngine

Motor de normalización post-extracción.

Agrupa instancias por tipo de modelo normalizado, batchea llamadas al LLM con structured output (una llamada por batch), y aplica los resultados mediante mapeo explícito por clave única.

__init__ 

__init__(
    llm: BaseLanguageModel,
    batch_size: int = 5,
    concurrency: int = _DEFAULT_CONCURRENCY,
) -> None

Parameters:

Name Type Description Default
llm BaseLanguageModel

Modelo de LangChain para las llamadas de normalización.

 required
batch_size int

Número máximo de entradas por batch LLM.

 5
concurrency int

Máximo de llamadas LLM en paralelo.

 _DEFAULT_CONCURRENCY

apply_cached_to_instance 

apply_cached_to_instance(
    instance: BaseModel, field_name: str, unique_key: str
) -> bool

Apply cached normalization result to a specific instance field.

Returns True if the key was found in cache and applied, False otherwise.

normalize_instances async 

normalize_instances(
    instances: list[tuple[type[BaseModel], BaseModel]],
) -> list[tuple[type[BaseModel], BaseModel]]

Normaliza los campos marcados en una lista de instancias.

Parameters:

Name Type Description Default
instances list[tuple[type[BaseModel], BaseModel]]

Lista de (model_class, instance).

 required

Returns:

Type Description
list[tuple[type[BaseModel], BaseModel]]

Lista de instancias con campos normalizados rellenados.

process_key_batch async 

process_key_batch(
    entries: list[NormalizationEntry], retry_count: int = 0
) -> dict[str, BaseModel]

Process a batch of unique normalization keys via LLM.

Returns {unique_key: normalized_result} for successfully processed keys. Results are cached in self.result_cache for reuse across batches.

Utility Functions

scinr.newton.tabular.normalization.run_normalization_hook async 

run_normalization_hook(
    instances: list[tuple[type[BaseModel], BaseModel]],
    engine: NormalizationEngine | None = None,
) -> list[tuple[type[BaseModel], BaseModel]]

Hook a insertar en el pipeline tabular entre instanciación y escritura.

Si engine es None, retorna las instancias sin modificar (no-op).

Parameters:

Name Type Description Default
instances list[tuple[type[BaseModel], BaseModel]]

Lista de (model_class, instance) recién instanciadas.

 required
engine NormalizationEngine | None

Motor de normalización configurado.

 None

Returns:

Type Description
list[tuple[type[BaseModel], BaseModel]]

Lista de instancias con campos normalizados rellenados.

scinr.newton.tabular.normalization.get_normalization_specs 

get_normalization_specs(
    model_class: type[BaseModel],
) -> list[NormalizationSpec]

Dada una clase Pydantic, retorna los campos marcados para normalización.

Un campo se considera marcable si: - Su json_schema_extra contiene normalization_model: True - Su tipo es (o contiene) un modelo Pydantic (no str, int, etc.)

Si normalization_source_fields no se especifica o está vacío, se usan TODOS los campos del modelo como fuente de datos.

scinr.newton.tabular.normalization.instance_has_normalizable_fields 

instance_has_normalizable_fields(
    model_class: type[BaseModel],
) -> bool

Retorna True si el modelo tiene al menos un campo normalizable.

scinr.newton.tabular.normalization.extract_source_values 

extract_source_values(
    spec: NormalizationSpec, instance: BaseModel
) -> dict[str, Any]

Extrae los valores de los campos fuente de una instancia.

Si spec.source_fields es None, usa TODOS los campos del modelo (excepto los que ya son modelos normalizados o el propio campo).