Saltar a contenido

Referencia de la API

Superficie pública de bayesrisk, organizada por dominio. Cada símbolo se genera automáticamente desde sus docstrings con mkdocstrings; las firmas y campos son los del código de la versión 2.17.0. La disponibilidad de esa versión se confirma en PyPI: esta referencia puede anticipar la publicación. Comprueba que la versión instalada corresponda a la capacidad que quieres usar.

Estabilidad (SemVer 2.x)

El pipeline de validación de scorecard (F1) —el trío run → Study → BayesRiskConfig y los dominios data, eda, binning, selection, model, scorecard, calibration, performance y stability— es API estable: no rompe hasta una versión 3.0. También lo son el informe (report), el trail de auditoría (audit), porque ya son superficie de integración, la puerta guiada (guided, bayesrisk.Scorecard), la escala maestra (master_scale) y el monitoreo (monitoring, bayesrisk.Monitor) y la comparación (comparison, bayesrisk.Comparison), desde que cerraron sus tres puertas. Las superficies que aún crecen (modelado ML, provisiones, survival, forward-looking, stress, validación, gobernanza y tracking) están marcadas como experimentales en su docstring, fuera de la garantía SemVer 2.x.

Esa lista no se escribe a mano en tres sitios: la fija bayesrisk.testing.stability y la verifican los gates del repositorio contra el docstring de cada paquete y contra esta página.

Núcleo liviano e import perezoso

import bayesrisk no arrastra el stack ML. bayesrisk.run se re-exporta de forma perezosa (PEP 562) desde bayesrisk.api, y los backends pesados de cada dominio (pandas, sklearn, statsmodels, optbinning, XGBoost, …) se cargan solo al ejecutar el paso correspondiente, tras sus extras opcionales.

Puerta guiada

bayesrisk.Scorecard construye, corre y cuenta un scorecard de comportamiento con la entrada mínima; es un cliente de run que arma el BayesRiskConfig, lo ejecuta y lee sus artefactos. Estable bajo SemVer 2.x desde que cerraron sus tres puertas (código, config completo y pantalla): su firma, sus resúmenes y sus decisiones (exclude, keep, merge_bins, set_bins, y las de la escala maestra, set_grades y set_cutoff) y apply para puntuar solicitudes nuevas sólo crecen de forma aditiva (ver Escala maestra).

Scorecard

Bases: _PuertaGuiada

Un scorecard de comportamiento de punta a punta, con la entrada mínima (D-FLU-1).

Parameters:

Name Type Description Default
data str | Path | DataFrame

Ruta a un CSV, Parquet o Excel, o un pandas.DataFrame. Los datos se copian al proyecto —un archivo, tal cual; un DataFrame, como Parquet— bajo <run_dir>/<name>/input/ con su huella en el nombre, y el config referencia esa copia: la inferencia y cada corrida leen exactamente los mismos bytes, y config.yaml + input/ reproducen la corrida por sí solos.

required
target str | _TargetRule

La columna 0/1 (o verdadero/falso) que dice quién es «malo», o una regla {"col": "dias_mora", "op": ">", "value": 90} con los operadores del motor.

required
id str | None

Identificador de cada operación, opcional y recomendado: una columna (llave de unicidad) o el nombre del índice del archivo. Sin él se usa el índice del archivo y se declara.

None
date str | None

El eje temporal: date= particiona por fecha de corte, cohort= por añada; sin eje, partition="random" explícito (D-OBL-5: la estrategia no se siembra). Exactamente uno.

None
cohort str | None

El eje temporal: date= particiona por fecha de corte, cohort= por añada; sin eje, partition="random" explícito (D-OBL-5: la estrategia no se siembra). Exactamente uno.

None
partition str | None

El eje temporal: date= particiona por fecha de corte, cohort= por añada; sin eje, partition="random" explícito (D-OBL-5: la estrategia no se siembra). Exactamente uno.

None
oot_from str | None

La frontera fuera de tiempo, obligatoria con date (fecha ISO) o con cohort (las cohortes reservadas). Si falta, la puerta se detiene antes de correr con el rango del archivo y el valor que usaría.

None
oot_cohorts str | None

La frontera fuera de tiempo, obligatoria con date (fecha ISO) o con cohort (las cohortes reservadas). Si falta, la puerta se detiene antes de correr con el rango del archivo y el valor que usaría.

None
holdout float

Proporción reservada como Holdout dentro de la muestra de desarrollo (0,2 de fábrica).

0.2
name str

Nombre de la versión del proyecto y carpeta raíz: la evidencia queda en <run_dir>/<name>/ (§8-8: "bayesrisk-runs" y "scorecard" de fábrica).

'scorecard'
run_dir str

Nombre de la versión del proyecto y carpeta raíz: la evidencia queda en <run_dir>/<name>/ (§8-8: "bayesrisk-runs" y "scorecard" de fábrica).

'scorecard'
purpose str | None

Con purpose se enciende la gobernanza y la ficha del modelo (D-GOB-8); sin él no hay ficha. owner y review_every (meses) completan la ficha.

None
owner str | None

Con purpose se enciende la gobernanza y la ficha del modelo (D-GOB-8); sin él no hay ficha. owner y review_every (meses) completan la ficha.

None
review_every str | None

Con purpose se enciende la gobernanza y la ficha del modelo (D-GOB-8); sin él no hay ficha. owner y review_every (meses) completan la ficha.

None
track str | Path | None

Ruta o URI de MLflow: enciende el registro de la corrida (D-FLU-9). Apagado sin él.

None
features Sequence[str] | None

Las predictoras y cuáles son categóricas. Si no se dan, se infieren y se declaran.

None
categorical Sequence[str] | None

Las predictoras y cuáles son categóricas. Si no se dan, se infieren y se declaran.

None
max_bins int
6
min_bin_size int
6
monotonic int
6
min_iv int
6
max_correlation int
6
max_vif int
6
stepwise int
6
p_enter int
6
p_exit float
0.05
sign_policy float
0.05
pdo float
0.05
target_score float
0.05
target_odds float
0.05
anchor float
0.05
target_pd float
0.05
deciles float
0.05
psi_thresholds tuple[float, float]

Los campos esenciales de cada etapa (§3.8 de la enmienda), con los valores del preset F1 de fábrica. Cada uno escribe una hoja existente del config; lo que no está aquí se alcanza por sc.config (la puerta completa).

(0.1, 0.25)
validation tuple[float, float]

Los campos esenciales de cada etapa (§3.8 de la enmienda), con los valores del preset F1 de fábrica. Cada uno escribe una hoja existente del config; lo que no está aquí se alcanza por sc.config (la puerta completa).

(0.1, 0.25)
document tuple[float, float]

Los campos esenciales de cada etapa (§3.8 de la enmienda), con los valores del preset F1 de fábrica. Cada uno escribe una hoja existente del config; lo que no está aquí se alcanza por sc.config (la puerta completa).

(0.1, 0.25)
formats tuple[float, float]

Los campos esenciales de cada etapa (§3.8 de la enmienda), con los valores del preset F1 de fábrica. Cada uno escribe una hoja existente del config; lo que no está aquí se alcanza por sc.config (la puerta completa).

(0.1, 0.25)

exclude

exclude(columns, *, reason)

Descarta variables en toda la corrida siguiente, con motivo.

Escribe binning.exclude_columns (D-EXC-1): la variable no se tramifica, no aparece en las tablas y no puede detener la corrida en «Tramos y WoE». La retira de las listas forzadas de selección y modelo —las dos rechazan forzar una variable que el binning ya no publica— (la última decisión sobre una variable gana). Sus tramos fijados con set_bins()/merge_bins() quedan en suspenso, y keep() los reactiva. La corrida siguiente (resume()) emite al trail un evento decision con autor usuario y este motivo.

keep

keep(columns, *, reason)

Fuerza variables a entrar al modelo, con motivo.

Escribe selection.force_include y model.force_include (sólo con la primera, model no vería una variable que selection descartó por IV, correlación o VIF) y las retira de las listas contrarias y de binning.exclude_columns. Una variable forzada que falle una validación dura del motor —signo invertido con la política en fail— sigue fallando: keep no apaga ninguna guarda.

bins

bins(column)

Los tramos de una variable numérica en la última corrida, numerados desde 1.

Es la tabla con la que se decide merge_bins/set_bins: número, rango, filas, malos, tasa de malos y WoE, leídos de la tabla de binning que el motor publicó (sin los tramos Special/Missing, que no tienen corte).

merge_bins

merge_bins(column, bins, *, reason)

Junta dos tramos adyacentes de una variable numérica, con motivo.

Los tramos se numeran como en :meth:bins (desde 1). Escribe la hoja binning.variable_overrides[<column>].user_splits con los cortes vigentes menos el que separaba esos dos tramos, todos fijados (user_splits_fixed): en la corrida siguiente el motor tramifica exactamente así y calcula el WoE de los tramos que resultan.

set_bins

set_bins(column, cuts, *, reason)

Fija los cortes de una variable numérica (los límites entre tramos), con motivo.

Escribe binning.variable_overrides[<column>].user_splits con esos cortes, todos fijados: en la corrida siguiente el motor tramifica exactamente así. Un tramo fijado que viole el tamaño mínimo o la monotonía declarada hace que el motor no tramifique la variable, y el resumen de «Tramos y WoE» lo dice.

set_grades

set_grades(cuts, *, reason)

Fija los cortes de los tramos de la escala maestra, en puntos, con motivo.

Es el set_bins de la escala: escribe master_scale.grade_edges (los cortes, en cualquier orden, se guardan ordenados) y la corrida siguiente usa esos tramos en vez de formarlos. Cada corte separa con la regla única: s ≥ c al lado de puntaje mayor. Un corte que deje un tramo sin operaciones de Desarrollo detiene la etapa con el tramo y el rango del puntaje.

set_cutoff

set_cutoff(score, *, reason)

Declara el puntaje de aprobación de la institución, con motivo.

Escribe master_scale.approval_cutoff: se aprueba el lado de menor riesgo del corte —con «más puntaje, menos riesgo», s ≥ score; con la dirección invertida, s < score— y la tabla de cortes gana su fila, calculada exactamente en ese puntaje. No tiene que ser un límite de tramo.

apply

apply(frame)

Puntúa solicitudes nuevas con la tarjeta de la última corrida (SDD-32 D-ESC-6).

Es el apply del bundle de aplicación (:class:~bayesrisk.scorecard.bundle. FittedScorecardBundle): una fila por solicitud con su puntaje, la PD calibrada y, con la escala maestra, su tramo (grade, 1 = menor riesgo), la PD del tramo (grade_pd) y, si hay corte declarado, la decisión (decision: "approve"/"reject"). Una fila que no se puede puntuar (scoring_status == "not_scorable") no recibe tramo ni decisión. Para llevar la tarjeta a otro sistema, bayesrisk.FittedScorecardBundle. from_study(sc.study).save(ruta).

export_excel

export_excel()

Un libro Excel por etapa, numerado, en <run_dir>/<name>/excel/ (D-FLU-5, D-SIM-7).

01 Datos y muestras.xlsx … 11 Escala maestra.xlsx para las etapas que corrieron —cada uno con el resumen, la tabla de decisión y las tablas completas que el informe publica para ese dominio, con la misma protección de celdas que los exports del informe— más 12 Decisiones.xlsx con las decisiones del registro de auditoría (humanas, de la puerta y del motor). Opcional: nunca es la vía para ver un resultado. Exige el extra excel (openpyxl); sin él se detiene con el comando de instalación.

compare

compare(other)

Dos corridas lado a lado: cifras clave, variables finales y decisiones humanas.

bayesrisk.Ecl calcula la provisión IFRS 9 de una cartera con la misma mecánica: el archivo de cartera y la historia de incumplimientos que alimenta la curva de PD, resúmenes por etapa en palabras de provisiones y dos decisiones con motivo (exclude sobre las covariables de la curva y rebut_backstops sobre las presunciones de mora). Su firma, sus métodos y la forma de sus resúmenes son estables bajo SemVer 2.x desde que la pantalla ofrece lo mismo —también los escenarios de la institución y las dos PD del modelo (history=, scenarios=, pd=, origination_pd=), desde la 2.10.0—; sus cifras siguen la marca experimental de survival, forward y provisioning, los motores que las calculan.

Ecl

Bases: _PuertaGuiada

La provisión IFRS 9 de una cartera, de punta a punta, con la entrada mínima (D-ECL-1).

La firma, los métodos y la forma de los resúmenes son estables (SemVer 2.x), también los escenarios y las dos PD del modelo desde que cerraron sus tres puertas (IFRS9-FIRMABLE capa C, D-SIM-1); las cifras siguen la marca experimental de survival, forward y provisioning (D-ECL-9).

Parameters:

Name Type Description Default
data str | Path | DataFrame

Ruta a un CSV, Parquet o Excel, o un pandas.DataFrame, con una fila por operación a la fecha de corte. Se copia al proyecto bajo <run_dir>/<name>/input/ con su huella en el nombre, y el config referencia esa copia: la inferencia y cada corrida leen exactamente los mismos bytes.

required
id str | None

Identificador de cada operación, opcional y recomendado: una columna o el nombre del índice del archivo. Sin él se usa el índice del archivo y se declara. Una columna se verifica única, y la curva, la provisión y el detalle por operación identifican cada operación por ella.

None
as_of str

Las columnas de la provisión: fecha de corte (un solo valor), cartera, exposición al incumplimiento ya calculada, LGD, tasa efectiva anual de cada operación y días de mora.

required
portfolio str

Las columnas de la provisión: fecha de corte (un solo valor), cartera, exposición al incumplimiento ya calculada, LGD, tasa efectiva anual de cada operación y días de mora.

required
exposure str

Las columnas de la provisión: fecha de corte (un solo valor), cartera, exposición al incumplimiento ya calculada, LGD, tasa efectiva anual de cada operación y días de mora.

required
lgd str

Las columnas de la provisión: fecha de corte (un solo valor), cartera, exposición al incumplimiento ya calculada, LGD, tasa efectiva anual de cada operación y días de mora.

required
rate str

Las columnas de la provisión: fecha de corte (un solo valor), cartera, exposición al incumplimiento ya calculada, LGD, tasa efectiva anual de cada operación y días de mora.

required
days_past_due str

Las columnas de la provisión: fecha de corte (un solo valor), cartera, exposición al incumplimiento ya calculada, LGD, tasa efectiva anual de cada operación y días de mora.

required
default str | None

La marca de incumplimiento (verdadero/falso), opcional: sin ella el Stage 3 lo asigna sólo la mora, y se declara.

None
origination str | None

Las fechas de otorgamiento y de vencimiento contractual de cada operación, opcionales (fechas AAAA-MM-DD o columnas de tipo fecha; una fila vacía es «sin fecha»). Con ellas la curva de PD se lee desde la antigüedad de cada operación —sin redondear— y la vida termina en su vencimiento (IFRS 9 5.5.19); el Stage 1 suma 12 meses o la vida, si es menor. Una operación ya vencida con saldo se provisiona con un período. Más allá del último período de la curva con incumplimientos observados, el riesgo se extiende con la media de los tres últimos. Supone que duration cuenta desde el otorgamiento.

None
maturity str | None

Las fechas de otorgamiento y de vencimiento contractual de cada operación, opcionales (fechas AAAA-MM-DD o columnas de tipo fecha; una fila vacía es «sin fecha»). Con ellas la curva de PD se lee desde la antigüedad de cada operación —sin redondear— y la vida termina en su vencimiento (IFRS 9 5.5.19); el Stage 1 suma 12 meses o la vida, si es menor. Una operación ya vencida con saldo se provisiona con un período. Más allá del último período de la curva con incumplimientos observados, el riesgo se extiende con la media de los tres últimos. Supone que duration cuenta desde el otorgamiento.

None
installment str | None

La cuota mensual del contrato, opcional; exige maturity. La exposición de cada período sigue la tabla de pagos de esa cuota hasta el vencimiento, con la tasa implícita en la cuota (no rate). Si la cuota no alcanza a pagar el saldo en el plazo, la exposición queda constante y se cuenta en «Qué revisar».

None
history str | Path | DataFrame | None

Los escenarios económicos de la institución (IFRS9-FIRMABLE; estables desde la capa C, con la pantalla y el informe), las dos juntas, como ruta (CSV, Parquet o Excel) o DataFrame. history es la historia larga de una tasa de incumplimiento de referencia —columnas date, default_rate como fracción (un 0,9 % va como 0,009) y las variables macro—; scenarios, las trayectorias de esas variables por escenario —scenario, weight, date y las mismas variables—, al menos dos, con pesos mayores que cero que suman 1 y que cubran los 12 meses siguientes al corte. El motor estima cuánto se mueve la tasa con la macro y desplaza en logit el riesgo de cada tramo de la curva según su fecha de calendario; la ECL es la ponderada de los escenarios. Se copian al proyecto con su huella, como data.

None
scenarios str | Path | DataFrame | None

Los escenarios económicos de la institución (IFRS9-FIRMABLE; estables desde la capa C, con la pantalla y el informe), las dos juntas, como ruta (CSV, Parquet o Excel) o DataFrame. history es la historia larga de una tasa de incumplimiento de referencia —columnas date, default_rate como fracción (un 0,9 % va como 0,009) y las variables macro—; scenarios, las trayectorias de esas variables por escenario —scenario, weight, date y las mismas variables—, al menos dos, con pesos mayores que cero que suman 1 y que cubran los 12 meses siguientes al corte. El motor estima cuánto se mueve la tasa con la macro y desplaza en logit el riesgo de cada tramo de la curva según su fecha de calendario; la ECL es la ponderada de los escenarios. Se copian al proyecto con su huella, como data.

None
pd str | None

La PD a 12 meses de hoy de cada operación, de tu scorecard o de tu modelo de rating (con bayesrisk, el bundle del scorecard aplicado a la cartera con bayesrisk.apply), y la del otorgamiento —tu score de admisión—, opcionales. Con pd la curva de cada operación se ancla a esa PD: conserva su forma por edad y su PD de los 12 meses siguientes al corte es la de tu modelo, también en la pérdida de por vida. Tiene que medir el mismo incumplimiento a 12 meses que la curva y ser a lo largo del ciclo: el resumen compara las dos medias y avisa si difieren en más de un 25 %. Con origination_pd (exige pd y origination) el aumento significativo del riesgo compara, para los 12 meses siguientes al corte, la PD de hoy —ponderada por escenario, si los hay— con la que se esperaba al otorgar para ese mismo tramo de vida. Una fila vacía es «sin dato»; una PD de 0, de 1 o fuera de ese rango se acota y se cuenta.

None
origination_pd str | None

La PD a 12 meses de hoy de cada operación, de tu scorecard o de tu modelo de rating (con bayesrisk, el bundle del scorecard aplicado a la cartera con bayesrisk.apply), y la del otorgamiento —tu score de admisión—, opcionales. Con pd la curva de cada operación se ancla a esa PD: conserva su forma por edad y su PD de los 12 meses siguientes al corte es la de tu modelo, también en la pérdida de por vida. Tiene que medir el mismo incumplimiento a 12 meses que la curva y ser a lo largo del ciclo: el resumen compara las dos medias y avisa si difieren en más de un 25 %. Con origination_pd (exige pd y origination) el aumento significativo del riesgo compara, para los 12 meses siguientes al corte, la PD de hoy —ponderada por escenario, si los hay— con la que se esperaba al otorgar para ese mismo tramo de vida. Una fila vacía es «sin dato»; una PD de 0, de 1 o fuera de ese rango se acota y se cuenta.

None
duration str

La historia de incumplimientos que alimenta la curva de PD: cuánto tiempo se observó cada operación (entero ≥ 1, en la unidad de period) y si incumplió (0/1).

required
event str

La historia de incumplimientos que alimenta la curva de PD: cuánto tiempo se observó cada operación (entero ≥ 1, en la unidad de period) y si incumplió (0/1).

required
period str

La unidad de duration: año, semestre, trimestre, mes, semana o día. No se puede inferir de un entero y declararla mal cambia la provisión; con ella se infiere el horizonte de 12 meses (un año son 1, 2, 4, 12, 52 o 365 períodos).

required
horizon int | None

Hasta cuántos períodos se proyecta la curva. Es un dato de la institución: si falta, la puerta se detiene antes de correr con el máximo que observan tus datos y el valor que usaría.

None
covariates Sequence[str] | None

Columnas numéricas con que la curva ordena el riesgo entre operaciones. Sin ellas, una sola curva para toda la cartera (se declara).

None
name str

Nombre de la versión y carpeta raíz: la evidencia queda en <run_dir>/<name>/ ("ecl" y "bayesrisk-runs" de fábrica).

'ecl'
run_dir str

Nombre de la versión y carpeta raíz: la evidencia queda en <run_dir>/<name>/ ("ecl" y "bayesrisk-runs" de fábrica).

'ecl'
purpose str | None

Como en bayesrisk.Scorecard: gobernanza y ficha con purpose; registro en MLflow con track; portada y formatos del informe.

None
owner str | None

Como en bayesrisk.Scorecard: gobernanza y ficha con purpose; registro en MLflow con track; portada y formatos del informe.

None
review_every str | None

Como en bayesrisk.Scorecard: gobernanza y ficha con purpose; registro en MLflow con track; portada y formatos del informe.

None
track str | None

Como en bayesrisk.Scorecard: gobernanza y ficha con purpose; registro en MLflow con track; portada y formatos del informe.

None
document str | None

Como en bayesrisk.Scorecard: gobernanza y ficha con purpose; registro en MLflow con track; portada y formatos del informe.

None
formats str | None

Como en bayesrisk.Scorecard: gobernanza y ficha con purpose; registro en MLflow con track; portada y formatos del informe.

None

exclude

exclude(columns, *, reason)

Retira covariables de la curva de PD en la corrida siguiente, con motivo.

Escribe survival.input.covariate_cols sin ellas y registra la decisión en config.decisions con la lista que queda como huella: viaja en to_yaml() y la corrida siguiente (resume()) la declara al trail con autor usuario y este motivo.

rebut_backstops

rebut_backstops(
    *, stage2_days=None, stage3_days=None, reason
)

Rebate las presunciones de mora de IFRS 9 (30 y 90 días), con motivo.

IFRS 9 presume un aumento significativo del riesgo con más de 30 días de mora (5.5.11) y el incumplimiento con 90 (B5.5.37), y admite rebatirlas sólo con información razonable y sustentable: por eso es una decisión con motivo y no una perilla suelta. Escribe provisioning_ifrs9.staging.dpd_sicr_backstop y/o dpd_default_backstop y registra en config.decisions los dos días que quedan como huella; el validador del staging rechaza un Stage 3 que empiece antes que el Stage 2.

export_excel

export_excel()

Un libro Excel por etapa, numerado, en <run_dir>/<name>/excel/ (D-ECL-10).

01 Cartera.xlsx, 02 Curva de PD.xlsx, 03 Escenarios.xlsx (con escenarios) y 04 Provisión IFRS 9.xlsx para las etapas que corrieron —cada uno con el resumen, la tabla de decisión, las tablas adicionales de la etapa y las tablas completas que el informe publica para ese dominio, con la misma protección de celdas que los exports del informe— más 05 Decisiones.xlsx con las decisiones del registro de auditoría (humanas, de la puerta y del motor). El número es la posición de la etapa y no se mueve en una corrida parcial ni sin escenarios. Opcional: nunca es la vía para ver un resultado. Exige el extra excel (openpyxl); sin él se detiene con el comando de instalación.

bayesrisk.Provision calcula provisión interna con PD y LGD declaradas, o compone un proyecto nuevo desde Scorecard. Es experimental: conserva la fórmula por grupos y no certifica la calidad de sus entradas. El recorrido guiado incluye el cuaderno, el informe y las tablas completas.

Provision

Bases: _PuertaGuiada

Provisión interna experimental con PD/LGD declaradas, sin reajustar esas entradas.

pd y lgd nombran columnas. La fórmula es la de grupos del motor vigente, y el detalle distribuye el total grupal por exposición. Sin id sólo se verifica el índice técnico; no se acredita unicidad económica. from_scorecard compone el pipeline de PD como un proyecto distinto, con cobertura completa y sin modificar evidencia del original.

Experimental (fuera de la garantía SemVer 2.x).

from_scorecard classmethod

from_scorecard(
    scorecard,
    *,
    as_of,
    portfolio,
    exposure,
    lgd,
    name="provision",
    run_dir="bayesrisk-runs",
)

Compone PD y provisión en otro proyecto; no reutiliza resultados de una corrida.

export_excel

export_excel()

Libros de las etapas realizadas, con resumen y tablas completas.

bayesrisk.Lgd entrena con historia y muestras declaradas y entrega bayesrisk.LgdModel, un predictor reutilizable en una cartera sin LGD observada. Ambas superficies son experimentales. El ajuste usa sólo entrenamiento; evaluación y media de referencia son descriptivas, sin certificación de calidad, transportabilidad ni independencia del pipeline.

Lgd

Bases: _PuertaGuiada

Ajusta sobre train declarado y evalúa aparte, sin partición automática.

Experimental (fuera de la garantía SemVer 2.x).

model_ property

model_

Predictor validado de un ajuste terminado; nunca el de un intento anterior.

export_excel

export_excel()

Libros de historia y ajuste con diagnóstico, población y predictor completo.

LgdModel dataclass

Media fraccional congelada; predict nunca ajusta ni lee un objetivo.

Experimental (fuera de la garantía SemVer 2.x).

validated

validated()

Revalida también objetos recuperados desde un Study confiado por la persona.

predict

predict(frame)

Aplica por nombres de covariable; conserva índice y omite columnas adicionales.

to_frame

to_frame()

Tabla de transporte canónica; no es la presentación legible del informe.

from_frame classmethod

from_frame(table)

Rechaza campos/versiones ajenos; construye un DTO fijo sólo tras validar la tabla.

bayesrisk.Monitor monitorea una tarjeta en uso con la misma mecánica: la tarjeta guardada, la cartera nueva con su columna de periodo y, si la hay, la de desenlace; por periodo dice si cambió la población, si el modelo sigue ordenando y si cada tramo acierta su PD, con un veredicto y su acción (ver Monitoreo). Estable desde la 2.14.0, con sus tres puertas: la guiada, el config completo y la pantalla (el trabajo «Monitorear un modelo en uso»), y con su informe y su libro Monitoreo.xlsx (mon.export_excel()).

Monitor

Bases: _PuertaGuiada

El monitoreo de una tarjeta en uso, periodo a periodo, con la entrada mínima (D-MNT-1).

Parameters:

Name Type Description Default
bundle str | Path | FittedScorecardBundle

La tarjeta: la carpeta donde se guardó (FittedScorecardBundle.save) o el objeto FittedScorecardBundle. Tiene que ser de esquema 4 —guardada desde la 2.13.0— y traer su escala maestra: congela la referencia de Desarrollo contra la que se compara (los cortes del puntaje, la participación por tramo y el AUC inicial de Holdout). Se copia al proyecto bajo <run_dir>/<name>/input/ con su huella en el nombre.

required
data str | Path | DataFrame

La cartera nueva: ruta a un CSV, Parquet o Excel, o un pandas.DataFrame, con las variables que la tarjeta necesita, la columna de periodo y, si la hay, la de desenlace. Se copia al proyecto con su huella, como en bayesrisk.Scorecard.

required
period str

La columna de periodo de cada operación: texto ("2024Q1"), número o fecha (una fecha se agrupa por mes). Una misma operación puede estar en varios periodos.

required
default str | None

La columna de desenlace, opcional: 1 malo, 0 bueno y vacío si todavía no madura. Sin ella sólo se mide la población.

None
name str

Nombre de la versión y carpeta raíz: la evidencia queda en <run_dir>/<name>/ ("monitoreo" y "bayesrisk-runs" de fábrica).

'monitoreo'
run_dir str

Nombre de la versión y carpeta raíz: la evidencia queda en <run_dir>/<name>/ ("monitoreo" y "bayesrisk-runs" de fábrica).

'monitoreo'

export_excel

export_excel()

Monitoreo.xlsx en <run_dir>/<name>/excel/: un libro único (SDD-33 §6.4).

Sus hojas son el resumen (el veredicto, su acción y qué revisar), los periodos (los cuatro indicadores y el veredicto de cada uno), cada tramo por periodo y el CSI de cada variable por periodo —las tablas del mismo resumen «Monitoreo» que el notebook, la pantalla y el informe—, más un índice. La corrida de monitoreo no tiene etapas previas que numerar. Opcional: nunca es la vía para ver un resultado. Exige el extra excel (openpyxl); sin él se detiene con el comando de instalación.

bayesrisk.Comparison pone lado a lado entre 2 y 10 corridas guardadas desde su resumen comparable —el comparable.json que deja toda corrida terminada de scorecard o de IFRS 9 desde la 2.15.0—: la comparabilidad, los modelos repetidos, la prueba de DeLong pareada, el índice de concentración del BCE, la frontera y la elección de la institución con choose (ver Comparación de modelos). Estable desde la 2.16.0, por las puertas guiada, completa y de pantalla. Incluye el «Informe de Comparación de Modelos», con sus dos gráficos, y el libro Comparación.xlsx (comp.export_excel()).

Comparison

Bases: _PuertaGuiada

La comparación de entre 2 y 10 corridas terminadas, con la entrada mínima (D-CMP-1).

Estable (API pública bajo SemVer 2.x) desde la 2.16.0.

Parameters:

Name Type Description Default
runs Sequence[Any]

Las corridas, en orden: la primera es la referencia. Cada una, un Scorecard, un Ecl o un Study ya corridos; la carpeta de una corrida guardada; o su comparable.json. Todas de la misma familia (scorecards o provisiones IFRS 9) y guardadas desde la 2.15.0.

required
name str

Nombre de la comparación y carpeta raíz: la evidencia queda en <run_dir>/<name>/ ("comparacion" y "bayesrisk-runs" de fábrica).

'comparacion'
run_dir str

Nombre de la comparación y carpeta raíz: la evidencia queda en <run_dir>/<name>/ ("comparacion" y "bayesrisk-runs" de fábrica).

'comparacion'

names property

names

Los nombres de las corridas comparadas, en orden; uno repetido lleva su posición.

choose

choose(name, *, reason)

Registra la corrida que eligió la institución, con su motivo, y vuelve a comparar.

La comparación no elige (D-CMP-6): muestra la frontera y la institución decide. La decisión queda en la sección decisions y en el registro de auditoría con su autor y motivo, atada a la huella del resumen elegido —no al nombre ni a la posición—: si esa corrida se reemplaza o su resumen cambia, la elección queda sin efecto y el resumen lo avisa. Volver a comparar toma milisegundos, así que la corrida es inmediata.

export_excel

export_excel()

Comparación.xlsx en <run_dir>/<name>/excel/: un libro único (SDD-34 §6.3).

Sus hojas son el resumen (la lectura y qué revisar), los modelos (la tabla de decisión, con las dos fronteras), las pruebas de DeLong pareadas, cada modelo en cada muestra, las variables —o, en IFRS 9, la provisión por etapa—, las corridas con su comparabilidad y un índice: las tablas del mismo resumen «Comparación» que el notebook y el informe. Opcional: nunca es la vía para ver un resultado. Exige el extra excel (openpyxl); sin él se detiene con el comando de instalación.

StageSummary dataclass

El resumen de una etapa: de 3 a 8 líneas, sus alertas y su tabla de decisión (D-SIM-5).

text

text(*, with_table=True)

El resumen como texto para la consola.

to_dict

to_dict()

El resumen como JSON transportable, con la tabla ya escrita como la lee una persona.

Es lo que consume la pantalla (D-FLU-8: Resultados lee la misma fuente que summary()): las celdas viajan formateadas por :func:_formatear —coma decimal, miles, «—» en las ausencias— para que el panel pinte exactamente lo que el notebook y la consola muestran, sin una segunda regla de formato en el front. Las tablas adicionales viajan en extra_tables sólo cuando la etapa las trae: un resumen sin ellas se serializa exactamente igual que antes de que existieran.

FinalSummary dataclass

El resumen final (D-FLU-4).

Ejecución y validación técnica por separado, cinco cifras, qué revisar, decisiones y archivos.

headline

headline()

Las dos líneas con que la puerta cierra una corrida en la consola.

El scorecard dice su ejecución y su validación técnica; una provisión, su ejecución y la cifra (la primera de sus cinco, la ECL total) con su cobertura.

text

text()

El resumen final como texto para la consola.

to_dict

to_dict()

El resumen final como JSON transportable (los dos estados, cifras, alertas, archivos).

Las etapas no viajan aquí: cada una se serializa con su propio :meth:StageSummary.to_dict. La familia de cartera agrega su título, su familia y sus supuestos; el scorecard se serializa exactamente igual que antes de que existieran.

Ejecución y estado de la corrida

Punto de entrada único (run) y las estructuras stateful que produce: el Study contenedor, su ArtifactStore namespaced, el RunContext (estado + lineage) y el LineageBundle reproducible. check_pipeline responde si un config se puede ejecutar, sin ejecutarlo.

run

run(
    config,
    *,
    artifacts=None,
    run_dir=None,
    preamble=(),
    on_step=None,
)

Ejecuta una corrida completa de extremo a extremo y devuelve el Study.

Superficie pública única de ejecución (CT-4): ensambla el AuditSink y el ModelInventory (assemble_run), corre el Study, y —solo en éxito y solo si governance.publish_to_inventory— publica la ModelCard en el inventario.

Semántica de fallo (D-UI-2, decidida). Study.run() es el primitivo fail-loud: ante un fallo marca status="failed", conserva el lineage y re-levanta. Esta función es el envoltorio de producto: captura el BayesRiskError y devuelve el Study parcial en vez de propagarlo. El fallo no se silencia pero tampoco explota. Por eso, el consumidor por código debe chequear study.run_context.status ("done" vs "failed") antes de leer los resultados.

Dónde quedan los resultados: en study.artifacts, indexado por (dominio, clave)::

study = bayesrisk.run(config)
assert study.run_context.status == "done"
study.artifacts.get("performance", "result")     # métricas de discriminación
study.artifacts.get("model", "coefficients")     # los betas del modelo
study.artifacts.keys()                           # todo lo que dejó la corrida

study.results es el resumen firmable de la corrida, no un duplicado del store: trae metrics —plano, "<dominio>.<metrica>", float finito— y metric_sections por dominio (D-GOB-1…3). Es lo que leen el model card y MLflow. Una métrica que el dominio no pudo evaluar no aparece; ausencia y cero no son lo mismo.

Dónde queda la evidencia en disco: en run_dir, y sólo si se pide (D-GOB-6). Con el default None la corrida no escribe nada, que es el comportamiento histórico: una librería que empieza a dejar archivos en el cwd de quien la importa es una regresión, no una mejora. Con un run_dir se escribe allí el layout de SDD-03 §6::

<run_dir>/audit_trail.jsonl   # si `audit` está activo (su nombre lo fija AuditConfig)
<run_dir>/environment.json    # si `audit` está activo y captura entorno
<run_dir>/model_card.json     # si `governance` está activa
<run_dir>/model_card.md       # idem
<run_dir>/comparable.json     # si terminó un scorecard o una provisión IFRS 9 (SDD-34)
<run_dir>/study/              # lo que produce `Study.save`: config, lineage y artefactos

Cada archivo aparece sólo si su sección está activa: audit sin governance deja trail y entorno, y no card. scenario_log.jsonl del layout de SDD-03 §6 no se escribe: hoy no tiene ningún productor, y crear un archivo vacío para cumplir el layout sería teatro.

Si run_dir ya contiene una corrida, no se mezcla con la nueva. El layout se construye en un hermano temporal y sustituye al destino sólo cuando está completo; la corrida previa se aparta a un respaldo lateral (.<nombre>.old.*) que se conserva. Si algo falla antes de ese punto —al ensamblar, durante la corrida o al escribir la evidencia—, la corrida previa queda exactamente donde estaba, y lo que la corrida fallida alcanzó a dejar —su audit-trail con el diagnóstico del fallo, sobre todo— se conserva al lado, en .<nombre>.failed.*, con la ruta anotada en la excepción; si no llegó a haber evidencia, no queda rastro. Un trail_filename absoluto que apunte dentro de run_dir se escribe también en el temporal y ocupa su lugar con la consolidación: nunca toca la corrida previa.

Entrar por la mitad. artifacts= permite traer resultados ya calculados. Las claves son las parejas (dominio, clave) declaradas en Step.requires/Step.provides; hay que apagar en el config la sección que produciría cualquiera de las claves inyectadas. El tipo lo valida el paso consumidor, no esta puerta. Toda corrida que recibe artefactos externos los enumera en lineage.injected_artifacts y declara que no es reconstruible sólo desde config y datos. Esta puerta es de código: la UI/HTTP no deserializa artefactos externos.

Declarar la procedencia y escuchar cada paso. preamble y on_step son los dos ganchos aditivos de :meth:Study.run: pares (step, payload) que se emiten al trail como decision justo después de run_start —la puerta guiada declara así sus inferencias y las decisiones humanas con motivo— y un callback (nombre_del_paso, study) tras cada paso, con el que esa puerta cuenta cada etapa al terminar. Ninguno cambia el cálculo ni el config_hash; sin ellos la corrida es exactamente la de siempre.

Dónde queda el diagnóstico. En study.run_context.error (:class:~bayesrisk.core.lineage.RunError): tipo de la excepción, mensaje del motor y paso que falló, sin que haya que configurar nada. El audit-trail lo repite en el evento run_end, pero sólo si el config declara un sink: los presets lo declaran desde D-GOB-8, pero un config escrito a mano puede traer audit: null, así que no dependa de él; y el lineage no guarda el error nunca (enmienda RUN-ERROR).

check_pipeline

check_pipeline(config, *, artifacts=None)

Responde si config es ejecutable, sin ejecutarlo, y con qué pasos.

Envoltorio de producto de :meth:~bayesrisk.core.study.Study.check_pipeline: donde el primitivo del núcleo re-levanta, esta función captura y devuelve el veredicto, igual que :func:run frente a Study.run (D-UI-2). Sirve para avisar mientras se edita —el usuario sabe que le falta encender una sección antes de apretar Ejecutar— y es la misma respuesta por código y por interfaz (D-PIPE-3).

No ejecuta pasos, no lee el dataset, no monta sinks ni inventario y no deja rastro de corrida: comprobar no es correr.

Captura Exception, no sólo BayesRiskError. Es deliberado y más amplio que :func:run: una comprobación existe para informar, así que tumbar a quien la llama —el formulario la invoca en cada tecleo— sería peor que cualquier fallo que quiera reportar. Un from_config de dominio puede levantar algo que no es de la familia del motor; is_domain_error lo declara en vez de disfrazarlo (D-PIPE-6).

Parameters:

Name Type Description Default
config BayesRiskConfig

Config ya reconstruido. Que reconstruya es precondición, no resultado: la validez del modelo Pydantic y la ejecutabilidad del pipeline son dos preguntas distintas (D-PIPE-1).

required
artifacts Iterable[ArtifactKey] | Mapping[ArtifactKey, Any] | None

Claves de artefactos que estarán disponibles al correr. Si se entrega un mapping, sus valores se ignoran: comprobar sólo necesita las claves. Una clave válida que ningún paso activo consume se publica en PipelineCheck.inert_artifacts en vez de bloquear.

None

Returns:

Type Description
PipelineCheck

executable=True + steps en orden, o executable=False + el diagnóstico del motor.

PipelineCheck dataclass

Veredicto de ejecutabilidad de un config, sin correr nada (D-PIPE-2/D-PIPE-3).

steps trae los pasos en el orden en que correrían —útil por sí solo: es lo que el usuario va a ejecutar—, y queda vacío si el config no es ejecutable, porque en ese caso no hay pipeline que anunciar.

message guarda str(exc) íntegro, con el código de marca si el motor lo trae al frente: esta es superficie de código, donde el código es el dato, igual que en :class:~bayesrisk.core.lineage.RunError. El copy público lo sanea al publicarlo (:func:~bayesrisk.core.markers.strip_declared_codes, D-ERR-4).

is_domain_error distingue el diagnóstico accionable por quien configura de una excepción inesperada, cuyo texto puede ser detalle interno sin valor para quien usa el formulario (mismo criterio que D-ERR-5).

inert_artifacts enumera, en orden canónico, las claves externas que ningún paso activo ni el cierre transversal del lineage consumirá. No vuelven el config inejecutable: son un aviso contra typos o material preparado para una sección todavía apagada.

Cubre dos familias, y el ValidationError no es un añadido cosmético: las secciones de dominio son Any en el schema raíz, así que un valor fuera de rango dentro de ellas no lo caza BayesRiskConfig.model_validate — lo caza la coacción que hace la resolución, y llega aquí como ValidationError de Pydantic. Es el diagnóstico más accionable que produce esta función (nombra el campo y la restricción); clasificarlo como «inesperado» lo habría ocultado justo en el caso más común.

assemble_run

assemble_run(config, *, run_dir=None, workdir=None)

Construye el AuditSink compuesto y el inventario real/no-op de una corrida.

core recibe ambos objetos ya resueltos: no importa audit, governance, tracking ni MLflow. Si governance.publish_to_inventory=True y falta el extra tracking, esta capa falla ruidoso con MissingDependencyError porque la publicación fue una petición explícita.

run_dir es el directorio de la corrida (D-GOB-6): contra él se resuelve el nombre relativo del audit-trail. Sin él, un trail_filename relativo es un error explícito (D-GOB-7). workdir es el hermano temporal donde :func:run construye la corrida antes de consolidarla: todo trail que caiga dentro de run_dir se abre allí (:func:_resolver_trail).

Study

Estado del experimento y orquestador de la corrida (SDD-01 §4/§7).

Un Study recién construido arranca en status="created" y serializa sin valores ficticios (DoD F0). :meth:run lo transiciona a running → done/failed y congela el lineage. El config es inmutable: su identidad se ancla al config_hash.

inert_injected_artifacts property

inert_injected_artifacts

Expone a la API las claves externas que ningún paso activo consume.

preamble property

preamble

Las declaraciones (paso, payload) que :meth:run emitió antes del primer paso.

Copia profunda de lo que se pasó en run(preamble=…), en el mismo orden; vacía si la corrida no declaró nada o todavía no corrió. Vive en run_context —se persiste con save y vuelve con load, para que un informe regenerado desde un Study recargado diga las mismas decisiones que el trail (capa C de FLUJO-GUIADO-SCORECARD)— y es de sólo lectura: mutar lo devuelto no toca el snapshot.

⚠️ El registro durable es el trail; ante una discrepancia, manda el trail. Cada declaración se añade aquí sólo después de que su emit terminó sin error, así que ante un sink que falla esto trae un prefijo de lo emitido, nunca más. Con un sink compuesto (FanOutSink con trail y tracking) que falle en uno de sus subordinados, el trail puede conservar una declaración que aquí no está: se omite, no se inventa. core no sabe cuál de los sinks compuestos es el durable (CT-4: recibe el sink ya resuelto), así que cerrar esa ventana es cosa de quien compone el sink.

set_audit_sink

set_audit_sink(sink)

Inyecta el AuditSink (ya compuesto por api/runner) y lo propaga al ArtifactStore.

Debe llamarse antes de :meth:run. core no compone FanOutSink ni resuelve el inventario (CT-4): toma un sink ya resuelto.

lineage_bundle

lineage_bundle()

Devuelve el :class:LineageBundle congelado en :meth:run; levanta si no se corrió.

run

run(steps=None, *, preamble=(), on_step=None)

Ejecuta el pipeline y devuelve self (encadenable).

El argumento steps tiene prioridad sobre config.run.steps. fail_fast=False no se soporta en v1: se emite un warning ruidoso (no un no-op silencioso) y se procede como True. Una excepción en un paso (con fail_fast=True) deja status="failed" pero conserva el lineage (evidencia de trazabilidad, SR 11-7), escribe el rastro del fallo en run_context.error (:class:~bayesrisk.core.lineage.RunError: tipo, mensaje y paso), sella finished_at, emite run_end y se re-levanta; el Study parcial sigue siendo guardable.

Dos ganchos aditivos, ambos opcionales y sin efecto sobre el cálculo (enmienda FLUJO-GUIADO-SCORECARD, D-FLU-1/D-FLU-3; el motor no cambia de resultado con ellos):

  • preamble: pares (step, payload) que se emiten al trail como eventos decision justo después de run_start y antes del primer paso, en ese orden. Es la vía con que una puerta de entrada declara su procedencia —qué infirió y qué decisión humana con motivo trae el config— sin construir un segundo sink ni tocar el sobre del evento: el payload es del llamador y viaja tal cual (las claves aditivas que la ficha no lee, como autor y motivo, se conservan; D-ERR-6). No emite nada si la resolución del pipeline falla: entonces el trail lleva run_start y el run_end con el diagnóstico.
  • on_step: se llama con (nombre_del_paso, self) después de que cada paso ejecutó y publicó sus métricas, para que quien orquesta pueda contar lo que ya está en el store (el resumen por etapa de la puerta guiada). Una excepción del gancho se propaga como fallo del paso en curso, con su rastro: silenciarla escondería un error del llamador dentro de una corrida que se diría completa.

check_pipeline

check_pipeline(steps=None)

Resuelve y valida el pipeline sin ejecutar nada; devuelve los pasos en orden.

Responde la pregunta «¿este config se puede correr?» antes de correrlo, que es lo que permite avisarlo mientras se edita en vez de al apretar Ejecutar (enmienda VALIDACION-PIPELINE, D-PIPE-3). La capacidad vive aquí, en el núcleo, y no en la capa UI: quien trabaja por código tiene la misma respuesta que quien usa el formulario, que es el requisito de paridad.

Es fail-loud como :meth:run: un config inejecutable levanta el ConfigError del motor con su diagnóstico. El envoltorio de producto que lo captura y devuelve un veredicto inspeccionable es :func:bayesrisk.check_pipeline, igual que :func:bayesrisk.run frente a :meth:run (D-UI-2).

No toca el run_context: no asigna run_id, no cambia status ni sella finished_at. Comprobar no es correr, y una comprobación no debe dejar rastro de corrida en el audit-trail. No lee el dataset ni escribe en disco, y cuesta ≤0,1 ms con los dominios ya importados (la primera llamada del proceso paga sus imports perezosos, ~1-3 s).

Sí tiene un efecto, y no es cosmético: :meth:_resolve_steps coacciona los sub-configs opacos a su clase real, exactamente como haría :meth:run, y esa coacción materializa los defaults que un config cargado de YAML no traía — con lo que el config_hash de este Study puede cambiar. Es convergente (coaccionar dos veces da lo mismo) y deja el config en el estado que tendría al correr, así que una corrida posterior sobre el mismo Study es consistente; pero quien compare hashes alrededor de esta llamada debe saberlo.

Lo que no hace es sembrar los RNG del proceso cuando el Study se construyó con apply_global_seed=False, que es como lo hace :func:bayesrisk.check_pipeline.

run_step

run_step(name)

Ejecuta un paso aislado y devuelve su resultado; no altera run_context.status.

Emite sólo los eventos del paso (no run_start/run_end) y exige sus prerequisitos presentes. En F0 BayesRiskConfig no expone secciones de dominio, así que la resolución levanta ConfigError (la orquestación de dominios llega en T2).

Se resuelve SIN contexto de dominios activos, a propósito (D-FX-1). [name] no es «el pipeline de esta invocación»: es un paso suelto sobre artefactos que ya deben estar en el store. Pasar {name} como conjunto activo convertiría la comprobación CT-1 de este método en vacua para cualquier paso cuyo requires se derive del contexto —run_step ('report') dejaría de exigir sus cards—, y la precedencia que D-FX-1 fija (steps= → config.run.steps → secciones no nulas) describe una corrida, no este atajo.

save

save(path)

Serializa el Study a un directorio de forma atómica (escribe-a-temporal-y-renombra).

Layout: config.yaml + run_metadata.json + lineage.json (si hay lineage) + artifacts/<domain>/<key>.joblib. Al sobrescribir, el directorio previo se aparta a un respaldo lateral antes de colocar el nuevo y se restaura si el swap falla. En el doble-fallo (falla el swap y también la restauración), el estudio previo queda preservado en el respaldo lateral .old.* y path podría quedar transitoriamente sin directorio válido; se prioriza no perder datos. El azar (seed_manager) no se guarda: se reconstruye en :meth:load. Devuelve el Path del directorio final.

load classmethod

load(path, *, trust=False)

Recarga un Study desde un directorio; reconstruye el azar y verifica el config_hash.

trust=False (default) rechaza un Study con artefactos pickle (vector de ejecución de código). Un config_hash que no coincide con el del lineage levanta :class:~bayesrisk.core.exceptions.ReproducibilityError; una divergencia de versiones de librerías sólo advierte. El SeedManager se reconstruye desde config.repro.seed.

Nota: el chequeo de config_hash detecta divergencia accidental entre config.yaml y el lineage, no manipulación maliciosa (el hash de referencia vive en el mismo directorio editable). La integridad fuerte recae en trust=True + control del origen del directorio.

Las secciones del config vuelven tipadas aunque el proceso no haya importado sus dominios: el registro de clases se puebla antes de validar el YAML (D-HASH-1/D-HASH-5). Hasta la 2.14.0 el primer load de un proceso las dejaba como dict —el registro se poblaba después, dentro de config_hash— y FittedScorecardBundle.from_study fallaba sobre él (S49).

ArtifactStore

Contenedor namespaced (domain, key) → valor con traza de auditoría por escritura.

El Study inyecta el sink de auditoría; si no se pasa, cae a NullAuditSink (nunca None), de modo que emitir es siempre seguro. get devuelve el mismo objeto guardado (identidad, sin copia defensiva).

set

set(domain, key, value, *, overwrite=False)

Escribe value bajo (domain, key) y emite un AuditEvent "artifact".

Si la clave ya existe y overwrite=False, levanta :class:~bayesrisk.core.exceptions.ArtifactExistsError. El payload del evento distingue creación de sobrescritura con el campo overwrite (trazabilidad SR 11-7). Convención del evento "artifact": step lleva el domain del artefacto (no el paso que lo escribió) y payload el (domain, key) completo; SDD-03 lo consume sin adivinar.

get

get(domain, key)

Devuelve el artefacto (domain, key) (el mismo objeto); ausente → error.

has

has(domain, key)

Indica si la clave (domain, key) está presente.

keys

keys()

Lista las claves (domain, key) presentes, en orden de inserción.

RunContext

Bases: BaseModel

Estado de vida de una corrida del Study.

Arranca en "created" (Study recién construido, serializable sin correr); run() lo transiciona created → running → done|failed y le cuelga el :class:LineageBundle congelado. No es frozen (run() muta su estado); extra="forbid" rechaza un campo intruso al recargar run_metadata.json.

LineageBundle

Bases: BaseModel

Bundle de trazabilidad de una corrida (gobernanza en el núcleo, §4 principio 3, SR 11-7).

Se construye al cierre del run (§7 paso 4); git_sha/data_hash/uv_lock_hash son | None por ausencia legítima (repo ausente, datos sin cargar, uv.lock ausente). data_hash es el hash del contenido lógico por bloques (no los bytes del Parquet, decisión D2); su cálculo vive en data/ (SDD-02), aquí sólo se declara el campo. extra="forbid" rechaza un campo intruso al revalidar el bundle desde disco (Study.load).

injected_artifacts enumera las claves que entraron desde fuera de la corrida. Su default vacío mantiene compatibles los bundles escritos antes de la puerta D-ART-7.

Step

Bases: Protocol

Lo que un dominio implementa para ser orquestable (SDD-01 §7).

@runtime_checkable permite isinstance(obj, Step) en el despacho del motor; sólo verifica la presencia de name/requires/provides/execute, no sus tipos ni firmas.

execute

execute(study, rng)

Ejecuta el paso: lee de study.artifacts, calcula y escribe su salida.

Configuración declarativa

BayesRiskConfig es la raíz del experimento (Pydantic v2): agrupa las secciones de reproducibilidad, orquestación y todos los dominios. Se acompaña de utilidades de identidad (config_hash), carga/volcado YAML y migración de esquema.

BayesRiskConfig

Bases: BayesRiskBaseConfig

Configuración completa del estudio: todas las secciones del pipeline en un solo objeto.

Cada sección es opcional: la que se deja vacía no se ejecuta, y BayesRiskConfig() sin argumentos construye un estudio con todas las secciones vacías. El orden de ejecución lo fija el motor, no el orden de los campos; audit, governance y tracking documentan y registran la corrida, pero no son pasos del pipeline.

RunConfig

Bases: BayesRiskBaseConfig

Parámetros de orquestación de la corrida.

ReproConfig

Bases: BayesRiskBaseConfig

Parámetros de reproducibilidad del experimento.

DecisionEntry

Bases: BayesRiskBaseConfig

Una decisión humana con motivo, tal como se tomó.

No es una opción que se configure: es el registro de algo que una persona decidió. Su efecto ya está escrito en las secciones del config que definen el modelo; la huella guarda cómo quedaron al decidir, para que cada corrida compruebe que la decisión sigue aplicada.

config_hash

config_hash(cfg)

Devuelve el SHA-256 hex (64 chars) del JSON canónico de las secciones computacionales.

Las secciones de dominio que lleguen opacas (un dict, porque el proceso aún no importó esa capa) se coaccionan antes de canonicalizar, de modo que el digest no dependa del orden de los import. Ver :func:_coaccionar_secciones_opacas y D-HASH-1.

Parameters:

Name Type Description Default
cfg BayesRiskConfig

Config ya validado del que derivar la identidad.

required

Returns:

Type Description
str

Digest hexadecimal SHA-256 del config sin las :data:INFRA_SECTIONS ni las rutas que excluye :func:_hash_exclude (la identidad depende del CONTENIDO de cada insumo, vía su huella, no de su ubicación en disco).

load_config

load_config(path)

Carga un :class:BayesRiskConfig desde un fichero YAML.

Parameters:

Name Type Description Default
path str or PathLike

Ruta del fichero YAML del config.

required

Returns:

Type Description
BayesRiskConfig

Config validado e inmutable.

Raises:

Type Description
ConfigError

Si el YAML no cumple el schema (campo desconocido, tipo/rango erróneo).

loads_config

loads_config(text)

Carga un :class:BayesRiskConfig desde un string YAML.

Parameters:

Name Type Description Default
text str

Contenido YAML del config (un mapeo en la raíz).

required

Returns:

Type Description
BayesRiskConfig

Config validado e inmutable.

Raises:

Type Description
ConfigError

Si el YAML no es un mapeo o no cumple el schema.

dump_config

dump_config(cfg, *, exclude_unset=False)

Serializa un :class:BayesRiskConfig a YAML legible (orden de declaración).

Parameters:

Name Type Description Default
cfg BayesRiskConfig

Config a volcar.

required
exclude_unset bool

Si es True, omite los campos que no fueron provistos explícitamente (toman su default al recargar). Hace el volcado determinista frente al estado de imports para las secciones de capa diferida (report/audit/governance/validation): un dict de entrada sin, p. ej., report.document produce el MISMO YAML se haya importado o no la capa que coacciona a ReportConfig (que materializaría document por default_factory). El default False conserva el volcado completo (lineage auditable de una corrida).

False

Returns:

Type Description
str

YAML con las claves en orden de declaración y las tildes sin escapar.

migrate

migrate(raw)

Aplica el version-gate y la cadena de migradores a un config crudo.

Parameters:

Name Type Description Default
raw dict[str, Any]

Config recién deserializado del YAML, antes de validar. Un dict sin schema_version asume la versión base del paquete.

required

Returns:

Type Description
dict[str, Any]

El config listo para BayesRiskConfig.model_validate (migrado si hacía falta).

Raises:

Type Description
ConfigError

Si schema_version no es una cadena SemVer válida.

ConfigVersionError

Si schema_version es mayor que la del paquete (config "del futuro").

MigrationNotFoundError

Si falta un migrador para completar algún salto de versión necesario.

migration

migration(from_version, to_version)

Registra un migrador puro dict -> dict para el salto from_version -> to_version.

Valida en import time la linealidad de la cadena: el destino avanza estrictamente sobre el origen y no existe ya otro migrador con el mismo origen (evita ciclos, pasos que no progresan y bifurcaciones que colgarían o desviarían :func:migrate).

Parameters:

Name Type Description Default
from_version str

Versiones SemVer de origen y destino del migrador.

required
to_version str

Versiones SemVer de origen y destino del migrador.

required

Returns:

Type Description
Callable[[Migrator], Migrator]

Decorador que registra la función en :data:_MIGRATORS y la devuelve intacta.

Raises:

Type Description
ConfigError

Si el destino no avanza sobre el origen, o si ya hay un migrador con ese origen.

Datos

Carga, validación de esquema, definición del target, particionado y hashing lógico del dataset (data_hash) que alimenta el lineage.

DataConfig

Bases: BayesRiskBaseConfig

Carga el dataset, valida su esquema, define el target y arma las particiones.

es_corrida_de_cartera property

es_corrida_de_cartera

True si la sección no declara target ni partición: una corrida de cartera.

requisitos_incumplidos_por_contexto

requisitos_incumplidos_por_contexto(contexto)

Una corrida de cartera con una etapa que modela el incumplimiento no se puede correr.

El DAG ya la detiene —DataStep deja de anunciar las etiquetas y las muestras—; esto le dice al formulario por qué, en palabras de negocio y anclado al campo que lo arregla, antes de apretar Ejecutar (D-ECL-2).

columnas_que_produce

columnas_que_produce()

Columnas que este paso añade al frame, y que las secciones de abajo pueden nombrar.

Con target y partición declarados, las cuatro se escriben sin condición — DataStep.execute llama a TargetDefinition.apply y a Partitioner.split siempre—, o sea que no hay rama que consultar: si esta sección corre, están. En una corrida de cartera (D-ECL-2) el paso no etiqueta ni particiona, y no produce ninguna.

🔴 Existen aquí porque el preflight compara contra el ARCHIVO y las secciones de abajo consumen la SALIDA de este paso. Medido: survival.input.event_col = "target" llega a done —el indicador de evento es el flag de malo, que es lo natural— y sin esta declaración el preflight lo acusaría de columna faltante. stability.temporal_column ya sufría lo mismo con tres valores alcanzables (D-RAM-6).

El import es perezoso por el ciclo: data/target.py y data/partition.py importan este módulo. Las constantes se toman de ellos y no se redeclaran: una constante duplicada que se mueva por un lado deja el preflight mintiendo por el otro, y este repo ya pagó una triplicada.

DataLoader

Carga el dataset crudo a pandas.DataFrame con copias defensivas.

from_config classmethod

from_config(cfg)

Construye un cargador desde DataConfig.load / LoadingConfig.

load

load(source=None, *, audit=None)

Carga source como DataFrame y devuelve una copia defensiva.

Parameters:

Name Type Description Default
source (str, Path, DataFrame or None)

Ruta CSV/Parquet/Excel (.xlsx) o DataFrame en memoria. Si es None, usa self.config.source; si ambos faltan, levanta DataValidationError. Excel solo se admite con backend='pandas'.

None
audit AuditSink or None

Reservado para la orquestación de DataStep; la carga no emite decisiones todavía.

None

Returns:

Type Description
DataFrame

Dataset cargado. Siempre es una copia nueva respecto de la fuente interna.

SchemaValidator

Valida columnas, tipos y reglas simples mediante pandera.

index_col se interpreta como el nombre del índice pandas ya existente: el validador no ejecuta set_index ni consume una columna ordinaria con ese nombre. Si el identificador vive como columna, debe declararse como ColumnSpec o en unique_keys; si vive en el índice, index_col exige que el índice tenga ese nombre y sea único.

from_config classmethod

from_config(cfg)

Construye un validador desde DataConfig.schema_ / SchemaConfig.

build_schema

build_schema()

Traduce SchemaConfig al contrato imperativo de pandera.

Returns:

Type Description
DataFrameSchema

Esquema con representaciones canónicas: int→int64, float→float64, str→str, bool→bool, category→category y datetime→datetime64[ns]. Al validar sin coerción, los tipos lógicos numéricos conservan el ancho y la nulabilidad del dtype físico de entrada.

validate

validate(df, *, audit=None)

Valida df y devuelve el DataFrame resultante de pandera.

Parameters:

Name Type Description Default
df DataFrame

Dataset a validar. No se muta in-place; si coerce=True pandera devuelve una copia con los tipos coaccionados.

required
audit AuditSink or None

Reservado para la orquestación de DataStep; la validación de esquema no emite decisiones todavía.

None

Returns:

Type Description
DataFrame

DataFrame validado, posiblemente coaccionado según ColumnSpec.coerce.

Raises:

Type Description
DataValidationError

Si pandera detecta incumplimientos. El mensaje agrega todos los fallos de failure_cases explicados en español: qué columna falta, qué tipo se esperaba o qué regla se incumplió. Es copy público, así que no transporta los literales de pandera (column_in_dataframe, not_nullable, in_range) ni el vocabulario de su volcado — los lee un usuario, no quien desarrolla la librería.

TargetDefinition

Deriva la etiqueta binaria desde reglas declarativas con precedencia explícita.

from_config classmethod

from_config(cfg)

Construye una definición desde DataConfig.target / TargetConfig.

apply

apply(df, *, audit=None)

Etiqueta df en una copia defensiva y devuelve el contenedor auditable.

Parameters:

Name Type Description Default
df DataFrame

Dataset validado sobre el que se evalúan las reglas de target. No se muta in-place.

required
audit AuditSink or None

Sumidero opcional para emitir eventos decision por exclusiones y ambigüedades.

None

Returns:

Type Description
LabeledFrame

Copia de df con target y label_status agregados, más resumen de clases.

Raises:

Type Description
ConfigError

Si una regla está vacía, referencia columnas inexistentes, usa un operador fuera de la allowlist o compara valores incompatibles con el dtype de la columna.

DataValidationError

Si la ventana declara fechas no datetime, si las columnas de salida colisionan con el input, o si el resultado queda sin buenos o sin malos.

Partitioner

Asigna particiones Dev/HO/OOT de forma estable por observación.

from_config classmethod

from_config(cfg)

Construye un particionador desde PartitionConfig.

split

split(lf, *, root_seed, rng, audit=None)

Particiona un LabeledFrame sin mutar el frame de entrada.

Parameters:

Name Type Description Default
lf LabeledFrame

Resultado de TargetDefinition.apply con columnas target y label_status.

required
root_seed int

Semilla raíz cruda: ancla la identidad estable por observación.

required
rng Generator

Generador derivado por core; reservado para sorteos auxiliares deterministas.

required
audit AuditSink or None

Sumidero opcional para emitir decisiones de estrategia y resumen.

None

Returns:

Type Description
PartitionResult

Copia del frame con partition categórico y ttd booleano.

Raises:

Type Description
ConfigError

Si la estrategia no existe en el factory local o su config es inconsistente.

DataValidationError

Si faltan columnas, hay particiones vacías o se viola el piso de malos.

suggest

suggest(lf)

Sugiere una PartitionConfig editable según señales temporales simples.

DataStep

Bases: AuditableMixin

Orquesta la secuencia canónica de datos y publica artefactos domain='data'.

from_config classmethod

from_config(cfg)

Construye DataStep desde BayesRiskConfig.data.

from_config_with_context classmethod

from_config_with_context(cfg, *, contexto)

La historia LGD conserva filas y usa sus propias muestras declaradas.

motivo_sin_proveer

motivo_sin_proveer(consumidor, clave)

Por qué este paso, activo, no produce clave para consumidor (D-ECL-2).

Lo consulta la validación del pipeline antes de correr: sin esto, una etapa que modela el incumplimiento en una corrida de cartera recibiría «active 'data'», que ya está activo.

execute

execute(study, rng)

Ejecuta load → schema → special → target → partition → hash → artefactos.

En una corrida de cartera (target y partición nulos, D-ECL-2) no etiqueta ni particiona: publica el frame validado, special, data_hash y una data_card de «no aplica», y devuelve el MaskedFrame.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

Proyección directa de la card: los tres son escalares que DataCardSection ya declara, así que aquí no hay reducción que decidir. Sin metric_sections: data no tiene hoy payload estructurado CT-2, y fabricar uno para llenar el hueco sería inventar (D-GOB-5).

Análisis exploratorio (EDA)

Perfiles por variable, calidad de datos, tasa de incumplimiento en el tiempo y su estabilidad temporal, antes de modelar. Cómo se lee cada pieza —y qué hace el motor cuando el archivo no trae fecha— está en la guía Análisis exploratorio.

Eje, indicador, causas y marcas

En los resultados —JSON, tablas, model card— cada uno viaja como su identificador; en la pantalla, en el informe y en las guías se lee como su palabra. Son el mismo dato, y cada correspondencia tiene una sola fuente en bayesrisk.eda.

Identificador Palabra Qué es Fuente
period por fecha de observación Eje efectivo de la tasa (axis de la card) bayesrisk.eda.default_rate.AXIS_LABELS
cohort por cohorte Ídem; puede ser el efectivo aunque el config diga period (axis_inferred) ídem
cv variación relativa Indicador de estabilidad temporal bayesrisk.eda.stability.STABILITY_INDICATOR_LABELS
max_relative_drift peor desvío Ídem ídem
trend_slope tendencia Ídem ídem
eje_cohorte eje de cohorte, sin orden cronológico Causa de no evaluar la señal (stability_not_evaluable_reason) bayesrisk.eda.stability.NOT_EVALUABLE_REASON_LABELS
pocos_periodos_evaluables menos de dos períodos con observaciones suficientes Ídem ídem
tasa_media_cero sin incumplimientos en los períodos evaluables Ídem; sólo con un indicador relativo ídem
sin_eje_temporal el archivo no trae un eje temporal que ordenar Ídem; la tasa no se pudo agrupar, así que no hay serie que mirar ídem
tasa_no_calculable la tasa por período no se pudo calcular Ídem; el cálculo de la tasa falló, así que no hay serie que mirar ídem
no_calculable no se pudo calcular Ídem; la señal falló por sí sola y la tasa se conserva entera ídem
sin_eje_temporal el archivo no trae columna de fecha ni cohorte declarada Causa de no evaluar la tasa (default_rate_not_evaluable_reason): sin columna de fecha y sin cohorte declarada no hay eje, la tabla por período sale vacía y la corrida sigue bayesrisk.eda.default_rate.DEFAULT_RATE_NOT_EVALUABLE_REASON_LABELS
no_calculable no se pudo calcular Ídem, cuando el cálculo falló: la tabla sale vacía, la tasa global se conserva si hubo población y la causa del motor viaja en failed_analyses ídem
near_constant casi constante Marca de calidad por columna bayesrisk.eda.quality.QUALITY_FLAG_LABELS
near_unique casi única Ídem ídem
high_cardinality alta cardinalidad Ídem ídem

La regla que gobierna la causa es una sola: hay causa si y sólo si el indicador configurado no es finito; entonces stability_value viaja como null y stability_flagged es false. Cuando el archivo no trae columna de fecha y la partición es por cohorte, el eje se infiere a esa cohorte y la decisión eje_eda_inferido queda en el trail de la corrida.

EdaStep nunca detiene la corrida: la tasa por período, la señal temporal, los perfiles y la calidad fallan por separado, cada uno publica su versión vacía y el paso publica siempre sus seis artefactos. La card trae failed_analyses —sub-análisis (default_rate, stability, univariate, quality, figures) → causa del motor—, vacío en toda corrida sana; cada falla deja una decisión analisis_exploratorio_parcial en el trail, y en el canal de métricas lo que no se calculó se omite en vez de publicarse como cero. Una excepción que no sea EdaError también degrada, pero su causa lleva el tipo: «error inesperado del motor (<Tipo>): …». Las piezas —DefaultRateAnalyzer, UnivariateProfiler, DataQualityProfiler— usadas por código siguen levantando su EdaError de siempre. Lo que se dice de cada uno y la frase que lo redacta viven en bayesrisk.eda.card (FAILED_ANALYSIS_LABELS, failed_analysis_sentence).

EdaConfig

Bases: BayesRiskBaseConfig

Describe la cartera antes de modelar: tasa de incumplimiento, perfiles y calidad de datos.

UnivariateProfiler

Calcula perfiles descriptivos de features candidatas frente al target.

from_config classmethod

from_config(cfg)

Construye un profiler desde UnivariateConfig.

profile

profile(frame, *, target_col, columns, audit=None)

Calcula perfiles univariados sobre filas con target elegible.

Parameters:

Name Type Description Default
frame DataFrame

Dataset etiquetado por data o equivalente standalone.

required
target_col str

Columna binaria nullable: 1 malo, 0 bueno, <NA> no elegible.

required
columns tuple[str, ...]

Columnas candidatas a perfilar. Una tupla vacía produce resultado vacío.

required
audit AuditSink or None

Reservado para compatibilidad con la orquestación; este profiler puro no emite eventos auditables y no aplica muestreo.

None

Returns:

Type Description
UnivariateResult

Diccionario columna-tabla y, si se pidió, IV descriptivo pre-binning.

Raises:

Type Description
EdaError

Si faltan columnas requeridas, el frame está vacío o el índice no es único.

DataQualityProfiler

Calcula missing, cardinalidad y flags descriptivos por columna.

from_config classmethod

from_config(cfg)

Construye un profiler desde QualityConfig.

profile

profile(frame, *, audit=None)

Calcula el diagnóstico de calidad sin mutar el DataFrame de entrada.

Parameters:

Name Type Description Default
frame DataFrame

Dataset validado por data o equivalente standalone. Se diagnostican todas sus columnas.

required
audit AuditSink or None

Reservado para compatibilidad con la orquestación; este profiler puro no emite eventos auditables.

None

Returns:

Type Description
QualityResult

Tabla con una fila por columna y flags descriptivos de calidad.

Raises:

Type Description
EdaError

Si el frame está vacío o el índice no identifica observaciones de forma única.

DefaultRateAnalyzer

Calcula la tasa de default sobre la población elegible del target.

from_config classmethod

from_config(cfg)

Construye un analizador desde DefaultRateConfig.

compute

compute(frame, *, target_col, audit=None)

Calcula la tasa de default por período/cohorte sin mutar el input.

Parameters:

Name Type Description Default
frame DataFrame

Dataset etiquetado por data o equivalente standalone.

required
target_col str

Columna binaria nullable: 1 malo, 0 bueno, <NA> no elegible.

required
audit AuditSink or None

Reservado para compatibilidad con la orquestación; este analizador puro no emite eventos auditables.

None

Returns:

Type Description
DefaultRateResult

Tabla agregada ordenada y tasa global ponderada por elegibles.

Raises:

Type Description
EdaError

Si faltan columnas requeridas, el eje temporal es ambiguo/no datetime o no hay filas que describir.

TemporalStabilityAnalyzer

Bases: AuditableMixin

Evalúa la estabilidad temporal descriptiva de la tasa de default cruda.

from_config classmethod

from_config(cfg)

Construye un analizador desde TemporalStabilityConfig.

assess

assess(default_rate, *, audit=None)

Calcula CV, drift relativo extremo y pendiente OLS de la tasa de default.

Parameters:

Name Type Description Default
default_rate DefaultRateResult

Resultado de DefaultRateAnalyzer.compute con axis='period' y la tabla by_period ordenable temporalmente.

required
audit AuditSink or None

Sumidero opcional para registrar la decisión auditable de redesarrollo o no evaluabilidad.

None

Returns:

Type Description
StabilityResult

Indicadores descriptivos, métrica configurada, umbral y bandera de señal.

Raises:

Type Description
EdaError

Si by_period no contiene las columnas mínimas del contrato de B5.2.

Notes

Con una tasa que no se pudo agrupar —sin columna de fecha ni cohorte declarada, D-SC-17— la señal sale no evaluable con la causa sin_eje_temporal, que se mira antes que el eje: la tabla llega vacía y «menos de dos períodos» describiría el síntoma en vez de la causa.

Con axis="cohort" la señal temporal no se evalúa y no es un error (D-SC-2, SDD-27 §8): las cohortes no tienen un orden cronológico que el motor pueda inferir, así que el resultado sale con los tres indicadores NaN, flagged=False y la causa eje_cohorte, y el trail registra la decisión no_evaluable —el mismo tratamiento que «menos de dos períodos»—. Hasta la capa 3 del scorecard completo este caso levantaba EdaError y con él moría la corrida entera de eda, tasa por cohorte incluida.

La regla que gobierna la causa es una sola, y se prueba en los dos sentidos: hay causa si y sólo si el indicador configurado no es finito. «Tasa media cero» (§0-13) sólo aplica a los indicadores relativos —cv y max_relative_drift—; con trend_slope el indicador vale cero, es evaluable y no hay causa.

no_calculable

no_calculable()

La señal cuyo PROPIO cálculo falló (D-SC-19): no evaluable, sin decisión en el trail.

La decisión la registra el paso, que es quien atrapó la falla y conoce su causa; aquí sólo se construye el resultado con la forma de siempre —tres indicadores NaN, sin señal—.

EdaStep

Bases: AuditableMixin

Orquesta EDA y publica artefactos domain='eda' sin mutar data.

from_config classmethod

from_config(cfg)

Construye EdaStep desde BayesRiskConfig.eda.

execute

execute(study, rng)

Ejecuta default_rate → stability → univariate → quality → figures.

EdaStep sólo lee el dominio data y sólo escribe el dominio eda. Para particiones, lee ("data", "splits") de forma condicional cuando analysis_partition no es "todas"; esa clave no entra en requires por decisión de frontera documentada en el módulo.

🔴 Nunca levanta (D-SC-19). El análisis exploratorio es descriptivo y ninguna etapa del modelo lo necesita, así que un error aquí cuesta un sub-análisis, no la corrida: la preparación, la tasa por período, la estabilidad, los perfiles y la calidad fallan por separado, cada uno publica su versión vacía y su causa va a failed_analyses de la card, al trail y —como alerta— a las superficies. El paso publica siempre sus seis artefactos. Se atrapa cualquier excepción, pero una que no sea EdaError —un defecto del motor— se publica con su tipo, para que no quede escondida. Las piezas (DefaultRateAnalyzer, los perfiladores), usadas sueltas, siguen levantando.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4, respuesta 6).

Proyección directa de la card: la tasa de incumplimiento observada, cuántos períodos o cohortes la componen y si la señal temporal quedó marcada. stability_flagged viaja como 1.0/0.0 porque el canal sólo admite float finito (D-GOB-2) y un bool lo rechaza como contrato roto; NaN en la tasa —sin elegibles— se omite, no se rellena.

Binning y WoE

Discretización supervisada con Weight of Evidence (WoE), monotonía controlada e IV (motor OptBinning tras el extra scoring).

BinningConfig

Bases: BayesRiskBaseConfig

Agrupa cada variable en tramos WoE y mide su poder predictivo con el IV.

requisitos_incumplidos_por_perfil

requisitos_incumplidos_por_perfil(perfil)

Invariantes que exigen mirar los DATOS, no sólo los nombres (D-PERF-3/4).

La invariante la declara aquí el dominio que la impone, igual que las de D-INV-1: es binning quien sabe que una columna de texto con casi un valor por fila no es un predictor.

El caso real que la motiva, medido con un CSV de cartera corriente: una columna id_operacion con un valor por fila entra por el comodín, OptBinning manda todas sus categorías al bin «otros», se queda sin ninguna y mata la corrida con un mensaje suyo, en inglés, que no nombra la columna. El paquete C ya dejó la salida —declararla en la llave de unicidad—; lo que faltaba era señalarla antes de pagar la corrida.

WoEBinner

Bases: TransformerMixin, BaseEstimator, BayesRiskTransformer

Wrapper sklearn-like sobre optbinning.BinningProcess para scorecard.

from_config classmethod

from_config(cfg)

Construye WoEBinner desde BinningConfig excluyendo el discriminador type.

fit

fit(X, y, *, special=None, sample_weight=None, audit=None)

Ajusta bins supervisados WoE/IV sin mutar X, y ni special.

Si el corte de categorías raras deja un solo nivel por debajo y ese grupo unitario queda sin una de las dos clases, la columna se reajusta una vez con el menor corte que deja dos niveles debajo (D-RAR-1). El intento y la reagrupación van a audit como dos decisiones —la primera antes de reajustar, la segunda sólo si el reajuste resuelve—, y el corte efectivo queda en rare_category_regroupings_.

Si un bin Missing o Special con observaciones queda sin una de las dos clases y su WoE es el empírico, se le asigna el del tramo regular de mayor tasa de malos observada de la misma variable —el de menor WoE; ante un empate, la primera fila—, con IV 0 en su fila (D-FAL-1). Cada asignación va a audit y a assigned_bins_, y la transformación usa ese mismo WoE.

Raises:

Type Description
BinningFitError

Si el target no es binario con ambas clases, si todas las variables son no binneables, si OptBinning no alcanza un estado aceptable, si alguna tabla publica WoE infinito o si un bin conserva una clase en cero —también tras el único reintento de D-RAR-1, con un mensaje que dice qué se intentó y qué salidas hay—.

transform

transform(X)

Transforma variables crudas a columnas WoE usando bins fiteados previamente.

transform_bins

transform_bins(X)

Publica la etiqueta congelada de cada bin sin recalcular cortes ni WoE.

fit_transform

fit_transform(X, y, **kwargs)

Ajusta el binner y devuelve el woe_frame para el mismo X.

BinningResult

Bases: BaseModel

Contenedor agregado de las salidas principales de binning.

BinningStep

Bases: AuditableMixin

Orquesta binning supervisado WoE/IV y publica artefactos domain='binning'.

from_config classmethod

from_config(cfg)

Construye BinningStep desde BayesRiskConfig.binning.

execute

execute(study, rng)

Ejecuta fit en Desarrollo y transform determinista sin consumir rng.

rng se recibe por el protocolo homogéneo de Step; binning v1 no introduce muestreo ni azar propio. La reproducibilidad depende de la matriz fija de datos/config/OptBinning.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

Los dos conteos que describen qué pudo binnearse. El IV por variable NO entra: es un mapa por variable, no un escalar del modelo, y aplanarlo publicaría una clave por columna en cada model card. Sin metric_sections (D-GOB-5).

Selección de variables

Filtrado pre-modelo por IV, correlación, VIF y estabilidad.

Motivos y bandas de IV

Cada variable candidata sale con un motivo (decisions[].reason) y con la banda diagnóstica de su IV (decisions[].iv_band). Igual que con las bandas de estabilidad, el identificador es el dato y la palabra es lo que se lee en pantalla y en el informe; las fuentes únicas son bayesrisk.selection.results.REASON_LABELS y bayesrisk.binning.results.IV_BAND_LABELS.

Motivo Palabra
included inclusión
business_include inclusión forzada de negocio
business_exclude exclusión de negocio
low_iv IV insuficiente
high_iv IV excesivo (posible fuga)
low_auc AUC insuficiente
low_ks KS insuficiente
low_gini Gini insuficiente
high_correlation correlación excesiva
high_vif VIF excesivo
cluster_representative_lost no ser representante de su clúster
constant_or_nonfinite ser constante o no finita
missing_binning_artifact faltar su artefacto de binning
forced_conflict conflicto entre reglas forzadas
high_stability inestabilidad temporal
Banda de IV Palabra
none sin poder
weak débil
medium medio
strong fuerte
suspicious sospechoso

SelectionConfig

Bases: BayesRiskBaseConfig

Filtra las variables WoE candidatas por IV, correlación, VIF y estabilidad PSI/CSI.

FeatureSelector

Bases: TransformerMixin, BaseEstimator, BayesRiskTransformer

Selector sklearn-like de columnas WoE para scorecard.

from_config classmethod

from_config(cfg)

Construye FeatureSelector desde SelectionConfig y sus sub-configs.

fit

fit(
    woe_frame,
    *,
    target_col,
    partition_col,
    binning_summary,
    woe_column_map,
    audit=None,
)

Ajusta filtros de selección sobre Desarrollo sin mutar artefactos de entrada.

transform

transform(woe_frame)

Filtra el frame WoE a columnas estructurales y variables seleccionadas.

fit_transform

fit_transform(woe_frame, **kwargs)

Ajusta la selección y devuelve el frame WoE filtrado para el mismo input.

SelectionResult

Bases: BaseModel

Contenedor agregado de las salidas principales de selection.

SelectionStep

Bases: AuditableMixin

Orquesta selección pre-modelo y publica artefactos domain='selection'.

from_config classmethod

from_config(cfg)

Construye SelectionStep desde BayesRiskConfig.selection.

execute

execute(study, rng)

Ejecuta fit en Desarrollo y transform determinista sin consumir rng.

rng se recibe por el protocolo homogéneo de Step; selection v1 no introduce muestreo ni azar propio. La reproducibilidad depende de datos, config y versiones instaladas.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

max_abs_correlation_after_selection es opcional en la card —sin pares que comparar no hay máximo— y se publica None para que el núcleo lo OMITA en vez de rellenarlo con 0.0, que leería como «cero correlación» cuando lo cierto es «no se pudo evaluar». Sin metric_sections (D-GOB-5).

Modelo (regresión logística PD)

Regresión logística sobre variables WoE con stepwise, política de signos e inferencia (statsmodels).

ModelConfig

Bases: BayesRiskBaseConfig

Ajusta la regresión logística de PD sobre las variables WoE seleccionadas.

LogisticPDModel

Bases: ClassifierMixin, BaseEstimator, BayesRiskClassifier

Modelo logístico PD sobre columnas WoE seleccionadas.

from_config classmethod

from_config(cfg)

Construye LogisticPDModel desde ModelConfig y sus sub-configs.

fit

fit(
    X,
    y,
    *,
    feature_names,
    woe_columns,
    iv_by_feature,
    audit=None,
    sample_weight=None,
)

Ajusta la logística PD y el stepwise usando sólo filas de Desarrollo.

decision_function

decision_function(X)

Devuelve el predictor lineal preservando índice y orden de entrada.

predict_pd

predict_pd(X)

Devuelve PD cruda P(target=1) preservando el índice original.

predict_proba

predict_proba(X)

Devuelve probabilidades [P(good), P(bad)] con el orden de entrada.

predict

predict(X)

Clasifica con umbral fijo 0.5; la calibración formal vive en SDD-10.

ModelResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por la capa model.

ModelStep

Bases: AuditableMixin

Orquesta ajuste logístico PD y publica artefactos domain='model'.

from_config classmethod

from_config(cfg)

Construye ModelStep desde BayesRiskConfig.model.

execute

execute(study, rng)

Ejecuta fit en Desarrollo y predicción PD determinista sin consumir rng.

rng se recibe por el protocolo homogéneo de Step; model v1 no introduce muestreo ni azar propio. La reproducibilidad depende de datos, config y versiones instaladas.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

Sólo el tamaño del modelo final. Los estadísticos de ajuste viven en ModelFitStatistics y son un DTO, no escalares del namespace: su lugar es metric_sections cuando SDD-08 declare qué va dentro.

metric_sections

metric_sections(study)

Publica el payload estructurado CT-2 de la card, sin aplanar (D-GOB-3).

Scorecard

Traducción de coeficientes a puntajes enteros (escala PDO / target odds), con overrides y redondeo controlado.

ScorecardConfig

Bases: BayesRiskBaseConfig

Traduce el log-odds del modelo a puntos de scorecard.

direccion_del_score_declarada

direccion_del_score_declarada()

Declara con qué orientación esta sección construye el puntaje (D-DIR-5).

Es el protocolo METODO_CONVENCION_SCORE del preflight, por convención de nombre y no por herencia, igual que requisitos_incumplidos. Existe para que el núcleo no tenga que leer config.scorecard.score_direction: con la sección opaca —el estado por defecto— ese atributo sería una clave de dict, y el núcleo pasaría a conocer el vocabulario de un dominio, que es justo lo que D-INV-1 rechazó.

Quien la construye es quien la declara: scorecard es la única sección que fabrica el puntaje (scaler.py:536-553 decide el signo de cada punto con este valor). performance y stability sólo lo miden, y por eso preguntan en vez de declarar.

PointsScaler

Bases: BayesRiskTransformer

Escala componentes log-odds de una logística WoE a puntos de scorecard.

from_config classmethod

from_config(cfg)

Construye PointsScaler desde ScorecardConfig excluyendo type.

fit

fit(
    *,
    coefficients,
    final_features,
    final_woe_columns,
    binning_tables,
    woe_column_map,
    audit=None,
    assigned_bins=None,
    bin_edges=None,
)

Deriva puntos por bin desde coeficientes y tablas WoE sin mutar entradas.

assigned_bins nombra, por variable, los bins auxiliares cuyo WoE asignó el binning (D-FAL-1). Comparten los puntos de su tramo de referencia —la primera fila con su mismo WoE, la que usa la búsqueda de puntos—: heredan su ajuste manual y no admiten uno propio.

bin_edges son los bordes efectivos que publica binning (D-CPY-3): con ellos, un ajuste manual de puntos casa con la etiqueta del motor o con el rótulo legible que muestran las tablas. Un ajuste que no casa con ninguno se declara en el trail (point_override_sin_casar); antes se ignoraba en silencio.

transform

transform(woe_frame)

Publica columnas de puntos y score total desde un frame WoE ya validado.

Scorecard

Bases: PointsScaler, TransformerMixin, BaseEstimator

Transformer sklearn-like que publica puntos por variable y score total.

fit_from_artifacts

fit_from_artifacts(
    *,
    model_result=None,
    binning_result=None,
    coefficients=None,
    final_features=None,
    final_woe_columns=None,
    binning_tables=None,
    woe_column_map=None,
    audit=None,
)

Ajusta el scorecard desde DTOs de model/binning o artefactos explícitos.

ScorecardResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por la capa scorecard.

ScorecardStep

Bases: AuditableMixin

Orquesta el escalamiento log-odds a puntos y publica domain='scorecard'.

from_config classmethod

from_config(cfg)

Construye ScorecardStep desde BayesRiskConfig.scorecard.

emit

emit(event)

Permite pasar el step como AuditSink a PointsScaler.

execute

execute(study, rng)

Ejecuta scorecard determinista sin consumir rng y publica cuatro artefactos.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

Sólo el tamaño de la tarjeta. pdo, target_score, factor y offset son PARÁMETROS de escalamiento elegidos por la institución, no resultados medidos: publicarlos como «métricas del modelo» es justamente el error que D-GOB-4 evita.

metric_sections

metric_sections(study)

Publica el payload estructurado CT-2 de la card, sin aplanar (D-GOB-3).

Calibración

Ajuste de la PD cruda a un ancla de negocio (through-the-cycle), con tope de offset auditable.

CalibrationConfig

Bases: BayesRiskBaseConfig

Ajusta la PD cruda del modelo a una tasa central de anclaje aprobada.

PDCalibrator

Bases: BayesRiskTransformer

Calibra PD cruda de una logística a una tasa central.

from_config classmethod

from_config(cfg)

Construye PDCalibrator desde CalibrationConfig excluyendo type.

fit

fit(raw_pd_frame, *, audit=None)

Ajusta parámetros de calibración usando sólo filas de Desarrollo.

transform

transform(raw_pd_frame)

Aplica la calibración fiteada y publica las ocho columnas canónicas.

fit_transform

fit_transform(raw_pd_frame, *, audit=None)

Ajusta el calibrador y devuelve el frame calibrado para la misma entrada.

CalibrationResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por la capa calibration.

CalibrationStep

Bases: AuditableMixin

Orquesta la calibración de PD cruda y publica domain='calibration'.

from_config classmethod

from_config(cfg)

Construye CalibrationStep desde BayesRiskConfig.calibration.

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Ejecuta calibration determinista sin consumir rng y publica cuatro artefactos.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

El ancla objetivo y las dos tasas que permiten juzgar si la calibración la alcanzó. Sin las tres juntas, calibrated_mean_pd_dev no dice nada por sí sola.

metric_sections

metric_sections(study)

Publica el payload estructurado CT-2 de la card, sin aplanar (D-GOB-3).

Desempeño

Métricas de discriminación (AUC/KS/Gini) y desempeño por decil, por partición.

PerformanceConfig

Bases: BayesRiskBaseConfig

Mide el desempeño del modelo ya ajustado: AUC, Gini, KS y tablas de gains por partición.

requisitos_incumplidos

requisitos_incumplidos(columnas)

Invariantes que el evaluador exige y que sólo se descubrían corriendo (D-INV-1).

No dependen del dataset —columnas va sin usar—, pero el protocolo la recibe igual porque el comprobador no sabe de antemano qué necesita cada dominio.

requisitos_incumplidos_por_contexto

requisitos_incumplidos_por_contexto(contexto)

Avisa si esta sección mide el puntaje al revés de como se construyó (D-DIR-5).

🔴 Es el defecto más caro que este repo ha medido, y no fallaba: publicaba. Con la tarjeta construida en un sentido y el desempeño midiendo en el otro, la corrida llega a done y el informe publica Gini -0,424 —un modelo con la discriminación invertida— con el validador, check_pipeline, check_dataset y la corrida los cuatro en verde y cero avisos.

Se avisa aunque hoy el valor sea inerte. Medido: la orientación sólo entra al cálculo con evaluation_source='score'; con la fuente por defecto no cambia ningún número. Callar en ese caso dejaría la contradicción escrita, publicada en la ficha del informe y lista para volverse mortal en cuanto alguien cambie la fuente con dos clicks — que es exactamente el camino por el que se llegó al Gini invertido.

PerformanceEvaluator

Bases: AuditableMixin, BaseBayesRiskEstimator

Calcula métricas discriminantes y deciles/gains para score o PD calibrada.

from_config classmethod

from_config(cfg)

Construye el evaluador desde PerformanceConfig excluyendo metadatos de schema.

evaluate

evaluate(
    frame,
    *,
    score_column,
    pd_column,
    target_column,
    partition_column,
)

Evalúa AUC/Gini/KS y tabla de deciles por partición.

Parameters:

Name Type Description Default
frame DataFrame

Frame analítico post-modelo con score, PD calibrada, target y partición.

required
score_column str

Columna del score operacional.

required
pd_column str

Columna de PD calibrada post-modelo.

required
target_column str

Columna target binaria, con 1 como default.

required
partition_column str

Columna que identifica desarrollo, holdout y oot.

required

Returns:

Type Description
PerformanceResult

DTO agregado con performance_table, discriminant_metrics, records y card.

PerformanceResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por la capa performance.

PerformanceStep

Bases: AuditableMixin

Orquesta desempeño post-modelo y publica domain='performance'.

from_config classmethod

from_config(cfg)

Construye PerformanceStep desde BayesRiskConfig.performance.

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Ejecuta performance determinista sin consumir rng y publica cuatro artefactos.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

🔴 Aquí hay REDUCCIÓN, no proyección: AUC, Gini y KS no son campos escalares de PerformanceCardSection —el único escalar declarado es n_deciles—, sino que viven en max_metrics_by_partition, un dict por partición. Se publica una clave por partición y métrica, auc_<partición>, porque colapsar las particiones a un número exigiría elegir cuál manda y esa elección es institucional, no del motor.

Una partición not_evaluable —cartera corta, sin ambas clases— trae None y el núcleo la OMITE. Es el caso real de una cartera pequeña, y publicar 0.0 ahí diría «AUC de 0.0», que es peor que no decir nada.

metric_sections

metric_sections(study)

Publica el payload estructurado CT-2 de la card, sin aplanar (D-GOB-3).

Estabilidad

PSI/CSI y estabilidad temporal del puntaje y de las características.

Bandas de estabilidad

Cada comparación se clasifica en una banda, y la banda fija de forma única la acción auditada. En los resultados —JSON, psi_table, stability_metrics, model card— la banda viaja como su identificador; en la pantalla, en el informe y en las guías se lee como su palabra. Son el mismo dato: la fuente única de la correspondencia es bayesrisk.stability.results.BAND_LABELS.

Identificador Palabra Acción auditada
stable Estable none
review Revisar vigilar
redevelop Redesarrollar redesarrollar
not_evaluable No evaluable none

El resumen de cada comparación publica juntos el peor PSI entre score y PD, la identidad de la magnitud ganadora (score_psi → «score», pd_psi → «PD calibrada», en bayesrisk.stability.results.PSI_METRIC_LABELS) y la banda de esa misma magnitud.

StabilityConfig

Bases: BayesRiskBaseConfig

Mide la estabilidad del score y de la PD calibrada con PSI y CSI.

requisitos_incumplidos

requisitos_incumplidos(columnas)

Invariantes que esta sección impone y que la corrida rechazaría (D-INV-1).

No son validaciones de forma —de eso se encarga _check_invariantes— sino exigencias sobre la combinación de campos y sobre el dataset, que hasta ahora sólo se descubrían pagando la corrida entera: el caso de origen de la enmienda moría en el paso 8 de 10 con el preflight y check_pipeline en verde.

requisitos_incumplidos_por_contexto

requisitos_incumplidos_por_contexto(contexto)

Avisa si esta sección describe el puntaje al revés de como se construyó (D-DIR-5).

⚠️ Aquí la consecuencia no es un número invertido: es un documento que se contradice. Medido, el motor de estabilidad no lee este campo en ningún cálculo —PSI y CSI comparan distribuciones binadas y son invariantes al signo—; el valor viaja del config a la ficha y de ahí al informe. Con la respuesta contraria a la de la tarjeta, el mismo documento afirma dos orientaciones distintas del mismo puntaje, y el lector no tiene cómo saber cuál rige.

requisitos_de_recalculo_declarados

requisitos_de_recalculo_declarados()

Qué artefactos leerá quien recalcule el PSI con esta sección (D-VAL-16; CT-1).

Lo consume el resolver del núcleo por convención de nombre (core.steps.METODO_REQUISITOS_RECALCULO) para armar el contexto con que validation declara su requires cuando apaga consume_stability: el recálculo reutiliza el ensamblador del paso de estabilidad, y lo que ese ensamblador lee lo deciden estos campos, que el paso de validación no puede mirar al construirse (D-INV-1, D-REQ-2).

Es la misma lista que compute_stability lee de verdad, con la exigencia conservadora que la enmienda declara como límite de CT-1: data.frame siempre que haya eje temporal —el ensamblador lo abre sólo si el score no trae la columna, y eso se sabe en ejecución—, y binning.bin_frame sólo con CSI por bins WoE. La ficha del scorecard no va aquí: se lee si está y no se exige (optional_requires del paso que recalcula).

StabilityEvaluator

Bases: AuditableMixin, BaseBayesRiskEstimator

Calcula PSI del score/PD, CSI por característica y estabilidad temporal post-modelo.

from_config classmethod

from_config(cfg)

Construye el evaluador desde StabilityConfig excluyendo metadatos de schema.

evaluate

evaluate(
    frame,
    *,
    score_column,
    pd_column,
    partition_column,
    feature_point_columns,
)

Evalúa PSI del score/PD, CSI por característica y estabilidad temporal por partición.

Parameters:

Name Type Description Default
frame DataFrame

Frame analítico post-modelo con score, PD calibrada, partición, columnas <feature>__points y, si aplica, la columna de período/cohorte.

required
score_column str

Columna del score operacional.

required
pd_column str

Columna de PD calibrada post-modelo, estrictamente en (0, 1).

required
partition_column str

Columna que identifica desarrollo, holdout y oot.

required
feature_point_columns Sequence[str]

Columnas <feature>__points cuya distribución de puntos alimenta el CSI.

required

Returns:

Type Description
StabilityResult

DTO agregado con psi_table, stability_metrics, records y card.

StabilityResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por la capa stability.

StabilityStep

Bases: AuditableMixin

Orquesta estabilidad post-modelo y publica domain='stability'.

from_config classmethod

from_config(cfg)

Construye StabilityStep desde BayesRiskConfig.stability.

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Ejecuta stability determinista sin consumir rng y publica cuatro artefactos.

El cálculo entero —ensamblar el frame y correr el evaluador— vive en :func:compute_stability, que es también lo que llama validation cuando recalcula el PSI (D-VAL-16): un solo camino, sin duplicar la alineación.

metrics

metrics(study)

Publica el resumen métrico del dominio al namespace canónico (D-GOB-4).

worst_psi es una REDUCCIÓN de max_psi_by_comparison (un dict por comparación): el peor caso es lo que gobierna la conclusión de estabilidad, y es la única forma de publicar un escalar sin elegir por la institución qué comparación importa. Sin ninguna comparación evaluable no hay peor caso, y la clave se omite en vez de valer 0.0 —que leería como «estabilidad perfecta», la lectura exactamente opuesta a la verdadera—.

metric_sections

metric_sections(study)

Publica el payload estructurado CT-2 de la card, sin aplanar (D-GOB-3).

Validación

Backtesting y pruebas regulatorias de discriminación, calibración y estabilidad (familias de tests). Cómo se lee el resultado —y qué hace un validador con él— está en la guía Validación formal.

La API histórica ValidationEvaluator.validate() y ValidationResult conserva sus cifras y su consolidación convencional. La lectura visible nueva se obtiene con bayesrisk.validation.interpret_validation(resultado, calibrated_pd=pares_originales, calibration_config=config.calibration): devuelve ValidationInterpretation, política hl_context_v1, sin recalcular HL. El Step publica ese DTO en ("validation", "interpretation") y sus grupos descriptivos en ("validation", "calibration_tie_groups").

Los conteos contextuales excluyen HL y Brier; los campos legacy_* conservan los históricos. Los metadatos opcionales calibration_parameters y calibration_card sólo acreditan una declaración sobre calibración, nunca independencia del pipeline. La falta de un contraste contextual validado se muestra explícitamente. Sin artefacto nuevo se identifica la lectura histórica; una política desconocida no se aplica por defecto.

Los artefactos se guardan con Study.save/load y conservan sus condiciones de confianza y el cotejo de config_hash. No hay firma ni digest individual de cada archivo joblib. El cotejo entre interpretación, card y tabla detecta incoherencias; no autentica el origen ni protege frente a una alteración coordinada.

interpret_validation

interpret_validation(
    result,
    *,
    calibrated_pd,
    calibration_config,
    calibration_parameters=None,
    calibration_card=None,
)

Interpreta un resultado y sus pares analíticos originales sin ejecutar HL otra vez.

La concordancia de agregados y configuración se comprueba; los agregados históricos no prueban por sí solos la identidad fila a fila. El llamante standalone debe proporcionar los pares originales. El Step usa exactamente su frame analítico recién evaluado. Metadatos ausentes o discordantes dejan contexto desconocido; datos contradictorios fallan.

ValidationInterpretation

Bases: BaseModel

Política versionada, separada del DTO histórico; tablas inmutables serializables.

calibration_tie_groups conserva las filas tipadas para persistencia y API standalone. El Step proyecta esas mismas filas a la clave tabular homónima; no vuelve a agrupar.

groups_frame

groups_frame()

Copia tabular defensiva de las filas; nulos reales, nunca inf/NaN en O/E.

Estado técnico y veredictos

Este apartado describe el ValidationResult histórico y sus tablas conservadas. ValidationInterpretation comparte el vocabulario, pero excluye HL de sus conteos y declara la falta de un contraste contextual: sólo HL/Brier deja «No evaluable»; otras pruebas favorables con HL solicitado dejan «Revisar: calibración pendiente».

En los resultados —JSON, tablas tidy, model card— cada estado viaja como su identificador; en la pantalla y en el informe se lee como su palabra. Son el mismo dato, y su correspondencia tiene una sola fuente: bayesrisk.validation.results.

Identificador Palabra Dónde aparece
pass Pasa Estado técnico histórico agregado
warn Revisar Ídem
fail Falla Ídem
not_evaluable No evaluable Ídem: ninguna prueba dejó un veredicto de pasa o falla y la estabilidad no dejó una decisión. La falta de potencia es una causa posible, no la única: también sale con sólo el puntaje de Brier, con sólo discriminación o con las pruebas de pasa o falla apagadas
pass Pasa Veredicto de una fila de calibración o de backtesting
fail Falla Ídem
not_evaluable Sin veredicto Ídem: sin potencia estadística, o una fila que no es una prueba de pasa/falla (el puntaje de Brier)
partition_below_min / group_below_min / degenerate_group / non_finite_statistic la muestra quedó bajo el mínimo de operaciones / un grupo de PD quedó bajo el mínimo de operaciones / un grupo de PD quedó sin variabilidad / el estadístico no fue finito con PD extremas Por qué un Hosmer-Lemeshow quedó sin veredicto (not_evaluable_reason); la card las enumera en metric_sections.validation.not_evaluable_partitions
green / amber / red Verde / Ámbar / Rojo Semáforo de un grado de rating
stability_artifact / recomputed Reusado de la etapa de estabilidad / Recalculado en esta etapa De dónde salió cada fila de la tabla de estabilidad (source); la card lo repite en metric_sections.validation.stability_source y, si se recalculó, dice con qué receta en stability_recompute (declared, la sección de estabilidad; minimal, sin eje temporal ni bins)

El estado técnico es evidencia del motor, no el veredicto sobre el modelo: aprobar, aprobar con observaciones o rechazar es una decisión de quien valida, y el informe lo declara explícitamente.

Familias y sus tablas

Identificador Palabra Tabla que publica
discrimination Discriminación Una fila por partición: población, AUC, Gini, KS, origen y estado
calibration Calibración Hosmer-Lemeshow y puntaje de Brier por partición, y el contraste por grado
stability Estabilidad El PSI de cada magnitud y comparación, con su banda
backtesting Backtesting Un contraste realizado-vs-estimado por parámetro y segmento

Los grupos de cada Hosmer-Lemeshow con veredicto se publican aparte, en ("validation", "hosmer_lemeshow_groups"): una fila por muestra y grupo, con los mismos grupos de la prueba —operaciones, malos observados y esperados, tasa observada, PD media, la diferencia en puntos porcentuales (gap_pp), la razón O/E (oe_ratio) y su aporte al estadístico (contribution), que sumado por muestra lo reproduce—. Sin Hosmer-Lemeshow, la tabla sale vacía.

Los grados sin potencia estadística no entran en la tabla de calibración ni en el conteo de pruebas: viajan aparte, en card.metric_sections.validation.not_evaluable_grades, con sus conteos y el mínimo técnico que los dejó fuera. Un Hosmer-Lemeshow sin veredicto sí está en la tabla —con statistic nulo y su causa— pero tampoco cuenta: n_tests y n_failed cuentan sólo las decisiones evaluables históricas. Los campos homónimos de ValidationInterpretation excluyen HL; PSI participa en la conclusión pero no en esos conteos.

ValidationConfig

Bases: BayesRiskBaseConfig

Valida el modelo con calibración y backtesting, y lo resume en un semáforo.

columnas_inactivas

columnas_inactivas()

La subsección entera de cada familia que no corre (D-RAM-1 + D-SUB-1).

🔴 Es la primera declaración del repo que nombra SUBMODELOS y no columnas sueltas, y hace falta porque la condición vive un nivel arriba de los campos que apaga: quien decide si la calibración lee grade_col no es binomial_by_grade sino, antes que él, families. Medido en evaluator.py::validate: cada familia entra por if "<familia>" in self.families, así que una familia deseleccionada no abre ninguna columna aunque sus flags queden encendidos — y quedan, porque deseleccionar una familia no los apaga.

El preflight poda el campo y su subárbol cuando el padre lo declara inactivo (dataset_check.py::_declaraciones, D-SUB-1), que es exactamente lo que hace falta aquí.

Las cuatro familias se llaman igual que sus cuatro sub-configs, y eso no es casualidad sino el contrato que un gate fija: una familia nueva sin su sub-config —o al revés— haría que este método suprimiera de más o de menos, en silencio.

requisitos_incumplidos

requisitos_incumplidos(columnas)

Invariantes que el evaluador exige y que sólo se descubrían corriendo (D-INV-1).

families vacío es el caso caro: el campo no tiene min_length, _check_validation sólo mira la coherencia backtesting↔enabled, y validation corre penúltimo en el F1 — así que un if de una línea tumbaba la corrida con todo el cómputo ya pagado.

ValidationEvaluator

Orquesta las familias de validación activas y consolida un :class:ValidationResult (§4).

from_config classmethod

from_config(cfg)

Construye ValidationEvaluator desde BayesRiskConfig.validation.

validate

validate(
    *,
    calibrated_pd=None,
    performance_metrics=None,
    stability_metrics=None,
    stability_source="stability_artifact",
    stability_recompute=None,
    ifrs9_detail=None,
    realised=None,
    model_ref="validation",
)

Ejecuta las familias activas en la secuencia canónica §7 y publica el resultado tidy.

calibrated_pd es el frame analítico común (§6): partition/target/ pd_calibrated/grade (nombres por config.calibration). Los artefactos consumidos (performance_metrics/stability_metrics) y los insumos de backtesting (ifrs9_detail/realised) se pasan tal cual; el evaluador copia todo en profundidad. stability_metrics llega siempre como un stability_metrics de SDD-11: el que publicó el paso de estabilidad (stability_source="stability_artifact") o el que el paso de validación recalculó con compute_stability ("recomputed", con la receta en stability_recompute; D-VAL-16). El evaluador no recalcula: sólo proyecta y publica la procedencia en la tabla y en la card. model_ref identifica el modelo validado en la card. Levanta un :class:~bayesrisk.validation.exceptions.ValidationConfigError si no hay familias activas o si una brecha crítica gatilla con fail_on_falta_dato=True.

hosmer_lemeshow_groups

hosmer_lemeshow_groups(calibrated_pd, calibration_records)

Grupos del Hosmer-Lemeshow de cada muestra con veredicto, una fila por grupo (D-HLG-1).

Recorre las muestras en el mismo orden y con el mismo subconjunto que :meth:_run_calibration y llama a :func:~bayesrisk.validation.calibration_tests.hosmer_lemeshow_groups, que comparte la partición del test: los grupos son los que decidieron el veredicto. Sólo las muestras cuyo Hosmer-Lemeshow tiene estadístico entran —una muestra sin veredicto (D-VAL-17) no tiene grupos que mostrar—; sin calibración, sin Hosmer-Lemeshow o sin ninguna muestra con veredicto, el frame sale vacío con sus columnas, y el paso lo publica igual.

ValidationResult

Bases: BaseModel

Contenedor agregado de los artefactos publicados por la capa validation (§4/§6).

ValidationStep

Bases: AuditableMixin

Orquesta la validación avanzada y publica domain='validation'.

from_config classmethod

from_config(cfg)

Construye ValidationStep desde BayesRiskConfig.validation (firma histórica).

Sin contexto, la ruta de recálculo declara los requires de la receta mínima y :meth:execute exige lo efectivo antes de calcular (D-REQ-4): un run_step('validation') con sección declarada que necesite data.frame o binning.bin_frame y no los tenga falla al entrar a execute con la clave exacta, no a mitad de cálculo.

from_config_with_context classmethod

from_config_with_context(cfg, *, contexto)

Fábrica contextual del resolver (D-FX-2): declara el requires de ESTA invocación.

Tercer implementador del hook. Con consume_stability=False lee contexto.requisitos_de_recalculo['stability'] y distingue tres estados (D-VAL-16): clave ausente → la sección no está declarada y el recálculo usará la receta mínima, así que se declaran sus dos claves y nada más; None → la sección está declarada pero no se pudo coaccionar, y como execute va a releerla el paso se detiene aquí, en el preflight, con ConfigError (check_pipeline lo acusa antes de ejecutar ningún paso); tupla → lo declarado. Es una precisión sobre D-REQ-4, no una excepción: degradar al default es correcto cuando el paso conserva el contrato que declararía solo; aquí va a leer esa sección, y un config inválido no puede pasar la comprobación previa.

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Ejecuta la validación determinista sin consumir rng y publica seis artefactos.

Escala maestra

Los tramos de riesgo del puntaje, la PD de cada tramo y la tabla de puntos de corte, al final del scorecard. Estable desde la 2.12.0, con sus tres puertas: la guiada (bayesrisk.Scorecard, que la corre por defecto), el config completo y la pantalla, que la corre en los trabajos del scorecard; el informe la publica en «Resultados» y el Excel en 11 Escala maestra.xlsx. Sus dos hojas son decisiones de la institución —sus cortes de tramo y su puntaje de aprobación—; las reglas de formación son constantes del motor.

MasterScaleConfig

Bases: BayesRiskBaseConfig

Los tramos de riesgo del puntaje, su PD y el punto de corte de la institución.

MasterScaleStep

Bases: AuditableMixin

Forma la escala maestra, le da su PD y publica la tabla de puntos de corte.

from_config classmethod

from_config(cfg)

Construye MasterScaleStep desde BayesRiskConfig.master_scale.

emit

emit(event)

Permite pasar el paso como AuditSink.

execute

execute(study, rng)

Forma la escala sobre Desarrollo, la lee en cada muestra y publica sus artefactos.

Monitoreo

Una corrida propia que parte de la tarjeta guardada y de la cartera nueva por periodo, sin volver a correr el desarrollo ni conservar sus datos: el PSI del puntaje y de la participación por tramo, la tasa de malos de cada tramo y de la cartera frente a su PD (en las dos direcciones), la discriminación —el AUC sobre los tramos contra el AUC inicial de la tarjeta y la pendiente de calibración— y un veredicto por periodo: sin acción, vigilar, recalibrar o redesarrollar. Estable desde la 2.14.0: salió en la 2.13.0 por la puerta guiada (bayesrisk.Monitor) y el config completo, y cerró sus tres puertas con la pantalla, el capítulo del informe y Monitoreo.xlsx. Sólo monitorea tarjetas guardadas desde la 2.13.0, que congelan la referencia de Desarrollo (esquema 4). Sus tres hojas son las entradas de la institución; los umbrales y la tabla de decisión son constantes del motor.

MonitoringConfig

Bases: BayesRiskBaseConfig

Monitorea una tarjeta en uso: población, orden y PD de sus tramos, periodo a periodo.

MonitoringStep

Bases: AuditableMixin

Monitorea una tarjeta en uso: población, calibración y discriminación por periodo.

from_config classmethod

from_config(cfg)

Construye MonitoringStep desde BayesRiskConfig.monitoring.

emit

emit(event)

Permite pasar el paso como AuditSink.

execute

execute(study, rng)

Aplica la tarjeta por periodo, mide los cuatro indicadores y publica el veredicto.

MonitoringVerdict

Bases: BaseModel

El veredicto de la corrida: el del último periodo, con su acción y su razón (§3.5).

Si el último periodo no tiene desenlace, se informa además el del último que sí lo tiene.

Comparación de modelos

Una corrida propia, sin datos, que lee el resumen comparable de cada corrida —sólo agregados y el riesgo de su muestra de evaluación, sin identificadores— y los pone lado a lado: si se midieron sobre las mismas operaciones, cuáles son el mismo modelo, qué diferencias de AUC son reales (DeLong pareada, corte 0,05), quién reparte mejor sus tramos (el índice del BCE) y la frontera, con un PSI común de receta de fábrica para todas. Estable desde la 2.16.0. Su única hoja son las corridas, en orden; la primera es la referencia.

ComparisonConfig

Bases: BayesRiskBaseConfig

Pone lado a lado entre 2 y 10 corridas guardadas, la primera como referencia.

ComparisonStep

Bases: AuditableMixin

Pone lado a lado los resúmenes comparables de entre 2 y 10 corridas terminadas.

from_config classmethod

from_config(cfg)

Construye ComparisonStep desde BayesRiskConfig.comparison.

emit

emit(event)

Permite pasar el paso como AuditSink.

execute

execute(study, rng)

Lee los resúmenes, compara, declara al registro y publica los artefactos de §6.2.

ComparisonCardSection

Bases: BaseModel

La ficha de la etapa: qué se comparó, cómo, la frontera, la elección y las constantes.

Backends ML

Modelos GBDT (XGBoost, LightGBM, CatBoost), random forest y SVM como extras selectivos, con monotonía y comparación challenger frente al scorecard.

MLConfig

Bases: BayesRiskBaseConfig

Entrena un challenger de machine learning que reta al scorecard campeón.

Compite sobre los mismos datos que el campeón.

contrato_de_variables_declarado

contrato_de_variables_declarado()

Publica de dónde salen las variables del challenger en ESTA corrida (D-REQ-3).

Lo consume el resolver del núcleo por convención de nombre (core.steps.METODO_CONTRATO_VARIABLES) para armar el contexto con que tuning y explain calculan su requires. Los dos pasos ajustan el mismo modelo que esta sección describe, así que leen artefactos distintos según lo que aquí se decida: con feature_source='selection_woe' el WoE lo publica selection, no binning.

🔴 Existe para que el núcleo no tenga que conocer estos dos campos. Podría leer config.ml.feature_source en dos líneas, y sería el acoplamiento que D-INV-1 rechazó: con la sección opaca —el estado por DEFECTO— eso es una clave de dict y el núcleo pasaría a depender del vocabulario de este dominio. Aquí el núcleo transporta un mapa de str cuyas claves no interpreta; quien las lee es quien las necesita.

⚠️ Son dos campos y no uno: hasta D-REQ-3, tuning declaraba binning.tables/binning.result, que sólo consume con monotonic.mode 'from_binning': con 'off' exigía dos artefactos que nunca lee.

🔴 data_raw NO se publica, y salió al implementar. Es una fuente diferida: el motor la rechaza siempre con FALTA-DATO-ML-1, nombrando la carencia y las dos salidas. Publicarla hacía que el paso declarase ('data','frame') como prerequisito duro, y entonces el DAG cortaba antes con «necesita 'frame', que produce 'data'» — un mensaje cierto y mucho peor, sobre un config que el motor iba a rechazar de todos modos. Omitirla no es declarar de menos: un paso con data_raw no llega a correr nunca, así que sus requisitos son irrelevantes y lo único que importa es cuál de los dos errores se lee.

MLResult

Bases: BaseModel

Contenedor agregado de los artefactos publicados por la capa ml (SDD-12 §4/§6).

term_structure

term_structure()

Retorna None: el challenger ML no publica estructura temporal (CT-2, SDD-12 §9).

A diferencia de IFRS 9/forward, ml produce una PD escalar por observación, no una curva multi-período; alimenta a report/governance por card + metric_sections.

comparison_frame

comparison_frame()

Materializa el tidy de :class:MLComparisonRecord (SDD-12 §6).

Preserva el orden de los registros (el MLStep los produce en el orden de config de particiones y métricas). Importa pandas de forma perezosa para no romper el import liviano de bayesrisk.ml.

MLStep

Bases: AuditableMixin

Orquesta el challenger ML y publica domain='ml' (SDD-12 §4/§7).

from_config classmethod

from_config(cfg)

Construye MLStep desde BayesRiskConfig.ml.

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Entrena, predice, compara, (opcional) calibra, audita y publica siete artefactos (§7).

Tuning de hiperparámetros

Optimización del espacio de búsqueda (Optuna) con muestreadores/pruners deterministas.

TuningConfig

Bases: BayesRiskBaseConfig

Busca con Optuna los hiperparámetros del challenger definido en ml.

resolve_search_space

resolve_search_space(ml_config)

Resuelve el espacio de búsqueda efectivo contra el backend de ml (SDD-13 §5).

tuning hereda el backend de ml (no lo duplica): un ml ausente impide tunear (:class:~bayesrisk.tuning.exceptions.TuningConfigError). Con search_space vacío devuelve default_search_space(ml.backend); si el usuario declaró claves, cada una debe ser un hiperparámetro del params-model del backend y su kind debe casar con el tipo del campo (:class:~bayesrisk.tuning.exceptions.TuningSearchSpaceError).

TuningResult

Bases: BaseModel

Contenedor agregado de los artefactos publicados por la capa tuning (SDD-13 §4/§6).

term_structure

term_structure()

Retorna None: el tuning no publica estructura temporal (CT-2, SDD-13 §9).

A diferencia de IFRS 9/forward, tuning produce hiperparámetros escalares y una curva de optimización, no una curva multi-período; alimenta a report/governance por card + metric_sections.

trials_frame

trials_frame()

Materializa el tidy de :class:TuningTrialRecord (SDD-13 §6).

Columnas number, param_<hiperparámetro> (unión estable en orden de aparición), value y state, en el orden de ejecución de los trials. Importa pandas de forma perezosa para no romper el import liviano de bayesrisk.tuning.

TuningStep

Bases: AuditableMixin

Orquesta la búsqueda de hiperparámetros y publica domain='tuning' (SDD-13 §4/§7).

from_config classmethod

from_config(cfg)

Construye TuningStep desde BayesRiskConfig.tuning (firma histórica).

from_config_with_context classmethod

from_config_with_context(cfg, *, contexto)

Fábrica contextual del resolver (D-FX-2): declara el requires de ESTA invocación.

Segundo implementador del hook, y la razón de que su contexto dejara de ser un frozenset[str]: saber que selection corre no basta —lo que decide qué artefactos lee este paso es qué eligió ml, no qué secciones existen— (D-REQ-2).

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Busca θ* con Optuna, valida invariantes, audita y publica siete artefactos (§7).

Explicabilidad

Explicaciones globales/locales (SHAP opcional) y reason codes para scorecard y modelos ML.

ExplainConfig

Bases: BayesRiskBaseConfig

Explica cada decisión con el aporte del scorecard, valores SHAP y reason codes.

ExplainResult

Bases: BaseModel

Contenedor agregado de los artefactos publicados por explain (SDD-14 §4/§6).

term_structure

term_structure()

Retorna None: la explicación no publica estructura temporal (CT-2, SDD-14 §9).

A diferencia de IFRS 9/forward, explain atribuye una predicción escalar por observación, no una curva multi-período; alimenta a report/governance por card + metric_sections.

global_frame

global_frame()

Materializa el tidy de :class:ShapGlobalRecord (SDD-14 §6).

Preserva el orden de los registros (el step los produce descendente por mean_abs_contribution con desempate lexicográfico). Importa pandas de forma perezosa para no romper el import liviano de bayesrisk.explain.

reason_codes_frame

reason_codes_frame()

Explota los reason codes a un tidy (observación · factor) (SDD-14 §6).

Recorre reason_codes (la vista top-N de shap_local) preservando el orden de las observaciones y, dentro de cada una, el orden por rank. Importa pandas de forma perezosa.

ExplainStep

Bases: AuditableMixin

Orquesta la explicabilidad unificada y publica domain='explain' (SDD-14 §4/§7).

from_config classmethod

from_config(cfg)

Construye ExplainStep desde BayesRiskConfig.explain (histórica, standalone).

from_config_with_context classmethod

from_config_with_context(cfg, *, contexto)

Fábrica contextual del resolver (D-FX-2): declara el requires de ESTA invocación.

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Explica ML (SHAP) y/o scorecard (analítico), audita y publica siete artefactos (§7).

Survival

Modelos de tiempo-a-evento: Kaplan-Meier, hazard discreto y Cox/AFT (algunos tras extra).

SurvivalConfig

Bases: BayesRiskBaseConfig

Modela el tiempo hasta el incumplimiento y obtiene de ahí la PD lifetime.

identificador_de_filas_declarado

identificador_de_filas_declarado()

La columna con que la curva identifica cada operación; None: el índice (D-CRE-6).

Desde CASO-REAL-IFRS9 la curva publica el valor de input.id_col como row_id en sus artefactos por operación; la provisión que la consume tiene que leer la misma columna, y lo comprueba con este valor (provisioning_ifrs9, requisito por contexto).

metodo_de_ajuste_declarado

metodo_de_ajuste_declarado()

El método con que se ajusta la curva (CASO-REAL-IFRS9 D-CRE-2, §3.2-7).

La provisión sólo lee la curva desde la edad de cada operación con discrete_hazard, el único método que publica los incumplimientos por período (la cola de la curva se extiende desde el último período con incumplimientos); lo comprueba con este valor (provisioning_ifrs9, requisito por contexto).

requisitos_incumplidos

requisitos_incumplidos(columnas)

Lo que esta sección se exige a sí misma y detiene la corrida al final (D-INV-1).

🔴 El caso es caro y era invisible: con los dos campos de la grilla en su default, el motor cae a los tiempos observados, emite DATO-INSTITUCIONAL-SUR-1 y —como fail_on_falta_dato viene en True— aborta en step.py:637-643, después de cargar el archivo, ajustar el modelo y calcular la term-structure. Medido con corridas reales: los cuatro métodos abortan, porque el fallback lo resuelve el paso y no cada motor.

Va en esta clase y no en las sub-secciones porque la condición necesita fail_on_falta_dato y method, que viven aquí. Es el mismo criterio por el que el gate del motor está en _card_from_model y no dentro de un motor.

⚠️ fail_on_falta_dato es parte de la condición, no un detalle: con él apagado la corrida llega a done y registra el aviso, así que avisar ahí sería un falso positivo —y el mensaje, que dice que la corrida se detendrá, sería literalmente falso—.

SUR-2 queda fuera con su razón medida: depende del CONTENIDO (todos censurados), no del config, y este protocolo sólo recibe nombres de columna.

SurvivalStep

Bases: AuditableMixin

Orquesta modelos survival y publica domain='survival'.

from_config classmethod

from_config(cfg)

Construye SurvivalStep desde BayesRiskConfig.survival.

emit

emit(event)

Permite pasar el step como AuditSink a los modelos survival.

execute

execute(study, rng)

Ejecuta survival determinista sin consumir rng y publica siete artefactos.

Cadenas de Markov

Estimación de matrices de transición y estructura temporal de PD por estados.

MarkovConfig

Bases: BayesRiskBaseConfig

Estima matrices de transición y la curva de PD lifetime desde un panel de migraciones.

MarkovStep

Bases: AuditableMixin

Orquesta matrices Markov y publica domain='markov'.

from_config classmethod

from_config(cfg)

Construye MarkovStep desde BayesRiskConfig.markov.

emit

emit(event)

Permite pasar el step como AuditSink sin exponer el sink interno.

execute

execute(study, rng)

Ejecuta Markov determinista sin consumir rng y publica siete artefactos.

Forward-looking

Proyección macroeconómica, modelos satélite y escenarios ponderados para PD point-in-time.

ForwardConfig

Bases: BayesRiskBaseConfig

Proyecta la PD con variables macroeconómicas y convierte entre PD PIT y PD TTC.

ForwardResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por la capa forward.

term_structure

term_structure()

Retorna la term-structure forward-looking tidy o None si no existe.

Cumple CT-2: SDD-16 puede consumir esta salida sin que forward importe ni instancie el motor ECL. pandas se importa perezosamente aquí para mantener liviano import bayesrisk.forward.results.

ForwardStep

Bases: AuditableMixin

Orquesta forward-looking y publica domain='forward'.

from_config classmethod

from_config(cfg)

Construye ForwardStep desde BayesRiskConfig.forward.

emit

emit(event)

Permite pasar el step como AuditSink sin exponer el sink interno.

motivo_sin_proveer

motivo_sin_proveer(consumidor, clave)

Por qué forward no produce el modelo del ciclo que pide la provisión (D-FIR-2).

execute

execute(study, rng)

Ejecuta el flujo forward determinista y publica las claves del dominio.

En la vía de los escenarios de la institución (D-FIR-2 y D-FIR-4) publica sólo ("forward", "cycle_model"); en la vía con modelo macro, las diez de siempre.

Stress testing

Escenarios de shock, barridos de sensibilidad y reverse stress sobre las métricas de provisión.

StressConfig

Bases: BayesRiskBaseConfig

Aplica escenarios de stress, sensibilidad y reverse stress sobre la cartera.

StressResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por la capa stress.

term_structure

term_structure()

Retorna la term-structure estresada tidy o None si no fue publicada.

Cumple CT-2: SDD-16/17 y reportes pueden consumir esta salida cuando existe. pandas se importa perezosamente aquí para mantener liviano import bayesrisk.stress.results.

scenarios

scenarios()

Retorna una copia de la tabla pública de escenarios/shocks aplicados.

tidy

tidy()

Retorna una copia de la tabla de impactos de stress.

StressStep

Bases: AuditableMixin

Orquesta stress testing severo y publica domain='stress'.

from_config classmethod

from_config(cfg)

Construye StressStep desde BayesRiskConfig.stress.

emit

emit(event)

Permite pasar el step como AuditSink sin exponer el sink interno.

execute

execute(study, rng)

Ejecuta el stress determinista y publica las nueve claves del dominio.

Provisiones

Dos marcos de provisión —IFRS 9/ECL y método interno (exposición por la tasa de pérdida del grupo, descompuesta en PD · LGD o provista directamente; jurisdiccionalmente neutro)— más una capa fina de orquestación que compara dos metodologías y aplica la regla declarada. El motor CMF (Chile) documentado más abajo es el caso de referencia de cómo se aterriza una norma local sobre esa base; su alcance y su fecha de verificación están en Aterrizar una norma local.

Sobre la regla del máximo

La regla del máximo del Capítulo B-1 (Circular N° 2.346 / 06.03.2024) es entre el método estándar de la CMF y el método interno del banco, y se aplica "para cada institución en Chile que consolida con el banco". No es un máximo entre la provisión CMF y el ECL de IFRS 9: el Compendio (Cap. A-2, num. 5) excluye el modelo de deterioro de NIIF 9 sobre las colocaciones y los créditos contingentes, porque esos criterios los define la propia CMF en B-1 a B-3. El comparativo CMF↔IFRS 9 que expone esta capa es un comparativo entre marcos contables (útil, por ejemplo, para reportar a una matriz extranjera), no una exigencia de la CMF.

ProvisioningConfig

Bases: BayesRiskBaseConfig

Compara dos fuentes de provisión configurables y aplica la regla declarada.

La regla del máximo del Cap. B-1 (Circular N° 2.346) es entre el método estándar de la CMF y el método interno del banco, por institución; comparar contra IFRS 9 es un contraste entre marcos contables, no la exigencia local.

sources property

sources

Par ordenado de dominios comparados (source_a, source_b).

consume_source_a property

consume_source_a

Consumo efectivo de la fuente A (el flag deprecado de su dominio manda si se informó).

consume_source_b property

consume_source_b

Consumo efectivo de la fuente B (el flag deprecado de su dominio manda si se informó).

portfolio_col_for

portfolio_col_for(source)

Columna de cartera declarada para el detail de la fuente indicada.

ProvisioningOrchestrator

Compara dos fuentes de provisión y aplica la regla declarada por celda (SDD-17 §6/§7).

from_config classmethod

from_config(cfg)

Construye el orquestador desde BayesRiskConfig.provisioning (revalida si aplica).

compare

compare(*, result_a, result_b, as_of_date, audit=None)

Aplica la regla (max / use_internal) por celda, determinista.

result_a y result_b son los resultados publicados por cfg.source_a y cfg.source_b respectivamente (posicionales por ranura, no por motor).

ProvisionOrchestrationResult

Bases: BaseModel

Contenedor agregado del comparativo de dos fuentes de provisión (SDD-17 §4/§6).

term_structure

term_structure()

Retorna la curva ECL de IFRS 9 (CT-2) o None si IFRS 9 no es fuente (SDD-17 §4).

Delega en la curva larga que IfrsProvisionResult.term_structure() publicó y que el orchestrator guardó en ifrs9_term_structure; la expone como copia defensiva. No fabrica una term-structure de la provisión reportada (que es escalar por celda): si IFRS 9 no participa retorna None — ni el CMF ni el método interno publican curva (D-CORE-7).

ProvisioningStep

Bases: AuditableMixin

Orquesta dos fuentes de provisión bajo la regla declarada (domain='provisioning').

from_config classmethod

from_config(cfg)

Construye ProvisioningStep desde BayesRiskConfig.provisioning.

emit

emit(event)

Permite pasar el step como AuditSink al orquestador (SDD-17 §9).

execute

execute(study, rng)

Aplica la regla a las dos fuentes sin usar rng y publica cuatro artefactos.

Motor CMF

CmfProvisioningConfig

Bases: BayesRiskBaseConfig

Calcula la provisión regulatoria CMF (Cap. B-1 y B-3) con el bundle de matrices versionado.

El bundle activo se elige en matrices.active_version.

Motor experimental: fuera de la garantía SemVer 2.x.

CmfProvisioningEngine

Calcula provisiones CMF B-1/B-3 con garantías verificadas o fail-fast.

from_config classmethod
from_config(cfg)

Construye el motor y carga las matrices CMF activas por config.

calculate
calculate(frame, *, pd_frame=None, as_of_date, audit=None)

Calcula detalle, resumen y card CMF preservando orden e índice del input.

CmfProvisionResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por provisioning.cmf.

term_structure
term_structure()

Retorna None en CMF B-1 agregado, cumpliendo CT-2/D-CORE-7.

El modelo estándar CMF B-1 publica provisión agregada y por operación, no una curva lifetime ni una estructura multi-período. SDD-17 usa summary/card para comparar el método estándar con la fuente configurada; no fabrica una curva para CMF.

Motor IFRS 9 / ECL

IfrsProvisioningConfig

Bases: BayesRiskBaseConfig

Calcula las provisiones contables IFRS 9: staging y pérdida esperada (ECL).

Motor experimental: fuera de la garantía SemVer 2.x.

requisitos_incumplidos_por_contexto
requisitos_incumplidos_por_contexto(contexto)

La curva y la provisión tienen que identificar las operaciones igual (D-CRE-6).

Con survival.input.id_col la curva publica el valor de esa columna como row_id; la provisión lo busca con row_id_col. Si una declara la columna y la otra no, o declaran columnas distintas, ninguna operación se encuentra con su curva y la corrida muere en la provisión, después de ajustar la curva. Se avisa antes de correr. Sólo con la curva de survival: la de forward hereda su row_id y la de markov tiene el suyo.

Y las fechas del contrato (D-CRE-2, §3.2-7): leer la curva desde la edad de cada operación exige sus incumplimientos por período, que sólo publica discrete_hazard; con otro método de survival, la corrida se detiene antes de correr.

lee_fechas_del_contrato
lee_fechas_del_contrato()

Si la provisión lee la curva con las fechas de cada operación (D-CRE-2, §3.2).

requisitos_incumplidos
requisitos_incumplidos(columnas)

Lo que esta sección se exige a sí misma y la corrida rechazará (D-INV-1).

🔴 El caso es el config DE FÁBRICA, y por eso importa tanto. Medido: los tres defaults —curva de survival, modo «ya viene a condiciones actuales» y escenarios de forward— construyen sin un solo error y revientan al calcular, porque las dos columnas que esas dos elecciones exigen —la marca de curva ajustada al momento y el peso de escenario— las publica únicamente forward: cero apariciones en survival/ y en markov/. Quien entra por el trabajo «Provisiones IFRS 9» recibe ese esqueleto; el preset F4 no lo sufre porque fija los tres a mano, o sea que el árbol ya sabía que los defaults no corren.

Va aquí y no en cada sub-sección porque la condición cruza dos de ellas: scenarios.source no puede juzgarse sin mirar pd.term_structure_source, que vive en su hermana. Es el mismo criterio con que la invariante de survival vive en la clase que ve method y el flag.

⚠️ No es un model_validator, y es deliberado. Las tres combinaciones son alcanzables y legítimas para quien inyecta su propia curva por código con esas columnas puestas; cerrarlas al construir mataría ese uso. Aquí se avisa (D-PRE-5, D-INV-3) y el motor sigue siendo la autoridad sobre sí mismo.

columnas no se usa: la exigencia es entre campos del config, no sobre el dataset.

IfrsProvisioningEngine

Motor económico IFRS 9 que orquesta la secuencia canónica de la ECL (SDD-16 §7).

from_config classmethod
from_config(cfg)

Construye el motor desde IfrsProvisioningConfig (molde hermano from_config).

calculate
calculate(
    frame,
    *,
    term_structure,
    calibrated_pd=None,
    as_of_date,
    audit=None,
    events_by_period=None,
    cycle=None,
)

Calcula la ECL IFRS 9 por operación y ensambla el :class:IfrsProvisionResult.

Parameters:

Name Type Description Default
frame DataFrame

DataFrame económico (exposición/drawn/límite, dpd, EIR, rating, LGD/recovery, flags). No se muta (copia defensiva).

required
term_structure DataFrame

Term-structure tidy lifetime PD del proveedor configurado (survival/markov/forward), con al menos row_id/period/time_value/pd_marginal. No se muta.

required
calibrated_pd DataFrame | None

PD 12m anclada por SDD-10 (columna pd_calibrated); obligatoria sólo cuando pd.base_pd_source='calibration'.

None
as_of_date str

Fecha de cálculo/cierre contable de la provisión (texto no vacío).

required
audit AuditSink | None

Sink de auditoría opcional (el step orquestador registra las decisiones de §9).

None
events_by_period Mapping[int, int] | None

Los incumplimientos de la historia de la curva por período (person_period de la card de discrete_hazard). Sólo se leen con las fechas del contrato (CASO-REAL-IFRS9 D-CRE-2): la cola de la curva se extiende desde el último período con incumplimientos.

None
cycle CycleInputs | None

El modelo del ciclo que publica forward y la historia de la curva (IFRS9-FIRMABLE D-FIR-1…3). Sólo con pd.pit_mode='cycle': la tabla de escenario × tramo queda en cycle_by_period_ tras calcular.

None

Returns:

Type Description
IfrsProvisionResult

Contenedor con staging/detail/ecl_term_structure/summary, los registros por operación y la card CT-2.

Raises:

Type Description
IfrsTermStructureError

Si la term-structure incumple el contrato tidy o sus invariantes.

IfrsConfigError

Si el modo PIT, la fuente de PD base o la fuente de escenarios exige insumos ausentes.

IfrsInputError

Si faltan columnas raíz del frame o los identificadores no son únicos/alineables.

MissingDependencyError

Si falta numpy o pandas.

IfrsProvisionResult

Bases: BaseModel

Contenedor agregado de artefactos publicados por provisioning.ifrs9 (SDD-16 §4).

term_structure
term_structure()

Retorna la term-structure de ECL en forma larga CT-2; nunca es None en IFRS 9.

Apila ecl_term_structure (ancho por componente) en la forma larga [row_id, scenario, period, time_value, component, value] que consumen SDD-17 y los reportes. Los componentes se preservan en orden canónico dentro de cada (row_id, scenario, period) y -0.0 se normaliza a 0.0.

Gobernanza

Model card (SR 11-7), inventario de modelos y registro de escenarios/overlays. Es la superficie de trazabilidad que run ensambla y (opcionalmente) publica al inventario.

GovernanceConfig

Bases: BayesRiskBaseConfig

Documenta el modelo para su gobierno: model card, inventario y diario de overlays.

Cambiar el propósito, los metadatos de inventario o la política de publicación no altera los resultados de la corrida ni su config_hash; el cambio queda registrado en el model card y en el audit-trail.

ModelCard

Bases: BaseModel

Ficha auditable del modelo, serializable a JSON canónico y markdown.

to_json

to_json()

Serializa el model card a JSON canónico para diff/auditoría.

to_markdown

to_markdown()

Renderiza una versión markdown estable del model card.

ModelCardBuilder

Ensambla un :class:ModelCard desde un Study finalizado y su trail.

build

build(study, *, trail_path=None)

Construye el model card desde lineage, resultados, artefactos y audit-trail.

ModelInventory

Bases: Protocol

Protocol SR 11-7 que SDD-04 implementa sobre MLflow Registry.

register debe ser idempotente por la ancla (model_name, nikodym.config_hash). Si el backend no soporta Registry, la implementación levanta RegistryUnavailableError.

register

register(entry)

Registra una entrada y devuelve el identificador de versión.

get_active

get_active(model_name)

Devuelve la versión activa del modelo, si existe.

list_versions

list_versions(model_name)

Lista las versiones conocidas del modelo.

NullInventory

Inventario no-operativo para publish_to_inventory=False.

register

register(entry)

No registra nada y devuelve cadena vacía por no-op consciente.

get_active

get_active(model_name)

Sin backend, no hay versión activa.

list_versions

list_versions(model_name)

Sin backend, no hay versiones.

InventoryEntry

Bases: BaseModel

Entrada completa que una implementación de inventario debe registrar.

publish_inventory

publish_inventory(entry, *, inventory=None)

Publica una entrada usando el inventario inyectado o NullInventory.

La resolución publish_to_inventory=True + extra tracking vive fuera de este módulo (B3.1c, assemble_run). Aquí solo se aplica el no-op explícito cuando el llamador entrega inventory=None.

ScenarioLog

Diario append-only de escenarios y overlays en JSONL canónico.

log_scenario

log_scenario(rec)

Añade un escenario al JSONL append-only.

log_overlay

log_overlay(rec)

Añade un overlay al JSONL, rechazando justificación vacía si fue manipulada.

read

read()

Lee y revalida todo el scenario_log en orden de escritura.

Auditoría, lineage y reproducibilidad

Audit sink JSONL, captura del entorno y hashing determinista de datos/archivos, más la relectura del trail para reconstruir la corrida.

AuditConfig

Bases: BayesRiskBaseConfig

Controla el audit-trail de la corrida y el snapshot del entorno de ejecución.

JsonlAuditSink

Sink que persiste el audit-trail a un archivo JSONL append-only.

emit

emit(event)

Serializa event como una línea JSON canónica y la añade al trail.

close

close()

Cierra el archivo de forma idempotente.

EnvironmentSnapshot

Bases: BaseModel

Registro serializable del entorno que acompaña a una corrida.

capture_environment

capture_environment(
    *,
    packages=None,
    uv_lock_path=None,
    now=None,
    version_provider=None,
    python_version_provider=None,
    platform_provider=None,
)

Captura versiones, plataforma, Python y hash de uv.lock.

Los proveedores son inyectables para que los tests fijen golden values exactos sin depender del entorno real del desarrollador.

hash_dataframe

hash_dataframe(df, *, algo='sha256')

Delegación perezosa al data_hash canónico de SDD-02.

hash_file

hash_file(path, *, algo='sha256')

Calcula el hash hexadecimal de un fichero leído por bloques.

read_trail

read_trail(path)

Lee todo el trail JSONL y devuelve una lista de AuditEvent revalidados.

iter_trail

iter_trail(path)

Itera eventos del trail, descartando líneas finales corruptas por crash.

Tracking (MLflow)

Registro opcional de corridas y modelos en un backend externo (MLflow), tras el extra correspondiente.

TrackingConfig

Bases: BayesRiskBaseConfig

Registra la corrida en MLflow y publica el modelo en el Model Registry.

Cambiar la URI, el experimento o la política de logging no altera los resultados de la corrida ni su config_hash, así que apuntar a otro destino no duplica versiones en el inventario.

TrackingRecorder

Frontera MLflow: traduce un Study ejecutado a un run auditable.

start_run

start_run(study, *, run_name=None)

Abre un run MLflow y devuelve un handle con sus identificadores.

ensure_run

ensure_run(*, run_name=None)

Abre un run si aún no existe; lo usa TrackingSink con eventos de core.

end_run

end_run(*, status='FINISHED')

Cierra el run activo si existe; doble cierre es no-op.

log_config

log_config(config)

Loguea params computacionales y tags de identidad del config.

log_metrics

log_metrics(results, *, step=None)

Loguea métricas finitas como metrics y el resto como results.json.

log_lineage

log_lineage(bundle)

Loguea lineage como tags de búsqueda y artefacto JSON.

log_study_dir

log_study_dir(path)

Adjunta el directorio serializado del Study bajo study/.

log_artifact_file

log_artifact_file(path, *, artifact_path=None)

Adjunta un fichero de artefacto al run activo.

register_model

register_model(model_uri, *, name=None, tags=None)

Registra un modelo vía el atajo MLflow de bajo nivel.

Con un Registry no respaldado por DB devuelve None + warning; el contrato regulatorio ruidoso vive en MLflowInventory.register.

snapshot_study

snapshot_study(study)

Guarda temporalmente el Study y adjunta su directorio si la config lo permite.

TrackingSink

Implementa AuditSink enrutando eventos del Study hacia TrackingRecorder.

emit

emit(event)

Procesa un evento de auditoría sin levantar hacia core por defecto.

MLflowInventory

Inventario SR 11-7 respaldado por MLflow Model Registry.

register

register(entry)

Registra entry idempotentemente por (model_name, config_hash).

get_active

get_active(model_name)

Devuelve la versión apuntada por el alias champion, si existe.

list_versions

list_versions(model_name)

Lista versiones rehidratadas desde tags del Registry.

list_models

list_models()

Lista modelos registrados con conteo y última versión.

get_version

get_version(name, version)

Lee una versión exacta; ausente levanta ModelNotFoundError.

latest_version

latest_version(name, *, alias=None)

Devuelve versión por alias o la última numérica; None si no existe.

Reportería

Reporte auditable del scorecard: ensamblado del bundle, render HTML/PDF y narración opcional (regla o IA).

ReportConfig

Bases: BayesRiskBaseConfig

Genera el informe auditable de la corrida y elige sus formatos de salida en formats.

ReportBuilder

Ensambla el documento lógico desde cards/results; no renderiza.

from_config classmethod

from_config(cfg)

Construye ReportBuilder desde BayesRiskConfig.report.

collect

collect(study)

Recolecta cards, tablas, figuras, parámetros y lineage en un snapshot defensivo.

build_sections

build_sections(bundle)

Construye el documento: capítulos, subsecciones de dominio y anexos.

El orden y los títulos salen de :data:~bayesrisk.report.document.CHAPTER_SPECS; la numeración (1-6 para capítulos, A/B/C para anexos) se deriva aquí, de modo que omitir un dominio no deja huecos en el índice.

Un capítulo con requires_domain informado es condicional: se omite entero si ese dominio no publicó card. La numeración se reajusta sola, porque se deriva de los capítulos efectivamente emitidos y no de la posición en CHAPTER_SPECS.

build_manifest

build_manifest(bundle, *, path)

Ensambla metadatos pre-render; el renderer completa el sha256 real.

HtmlReportRenderer

Render HTML standalone determinístico con Jinja2.

from_config classmethod

from_config(cfg)

Construye HtmlReportRenderer desde BayesRiskConfig.report.

render

render(bundle, *, ai_blocks=())

Renderiza HTML standalone byte-determinístico desde el bundle lógico.

build_manifest

build_manifest(html)

Construye el manifiesto HTML canónico sin escribir archivos.

write

write(html, *, output_dir)

Escribe el HTML en disco y devuelve un manifiesto reproducible.

PdfReportRenderer

Render opcional a PDF vía WeasyPrint sobre el HTML básico primario.

from_config classmethod

from_config(cfg)

Construye PdfReportRenderer desde BayesRiskConfig.report.

render

render(bundle, *, output_dir)

Renderiza y escribe el HTML básico y, si procede, un PDF opcional en disco.

El HTML determinístico es el artefacto primario: se escribe siempre y su manifest es el valor de retorno (igual que hoy con la ruta HTML). Con pdf.enabled se genera además un PDF con WeasyPrint (import perezoso) que se escribe como efecto secundario en {basename}.pdf y NO se refleja en el manifest. Si WeasyPrint no está disponible degrada a HTML (fail_if_unavailable=False) o re-lanza la dependencia ausente (True).

write_pdf_from_html

write_pdf_from_html(html, *, output_dir)

Escribe el PDF desde un HTML ya renderizado; devuelve su Path o None al degradar.

Recibe el HTML primario (que puede incluir la narrativa IA) y produce el PDF con WeasyPrint (import perezoso), sin re-renderizar el HTML. Degrada con gracia según pdf.fail_if_unavailable: en ausencia de WeasyPrint re-lanza la dependencia (True) o emite RuntimeWarning y devuelve None (False). En éxito escribe {basename}.pdf y devuelve el Path real en disco.

El warning propaga el diagnóstico de :func:~bayesrisk.report.pdf.render_pdf, que distingue "falta el paquete" de "el paquete está pero no encuentra sus nativas". Un texto genérico ("WeasyPrint no está disponible") describía mal el segundo caso —el más común en macOS y Windows, donde pip install bayesrisk[pdf] sí instaló WeasyPrint— y dejaba al usuario reinstalando un paquete que ya tenía.

ReportResult

Bases: _ReportBaseModel

Contenedor agregado publicado como salida final de la capa report.

md_path class-attribute instance-attribute

md_path = None

Ruta del .qmd (Quarto/Markdown): la fuente editable del informe, no un artefacto terminal. El analista escribe su contexto y sus conclusiones encima y compila su documento.

data_exports class-attribute instance-attribute

data_exports = Field(default_factory=dict)

{nombre de archivo: ruta real} de los adjuntos de datos (tablas por observación completas, ver :mod:bayesrisk.report.exports). Vacío si no se pidió csv ni xlsx.

ReportStep

Bases: AuditableMixin

Orquesta el reporte canónico F1 y publica domain='report'.

from_config classmethod

from_config(cfg)

Construye ReportStep desde BayesRiskConfig.report (firma histórica).

from_config_with_context classmethod

from_config_with_context(cfg, *, contexto)

Fábrica contextual del resolver (D-FX-2): recibe el contexto de ESTA invocación.

Study._resolve_step la prefiere sobre :meth:from_config cuando existe. Es la extensión genérica del resolver, no un caso especial de report: cualquier dominio cuyo contrato dependa de la invocación puede exponerla, y el que no la exponga no cambia.

⚠️ report sólo usa dominios_activos, que es lo que el contexto ya traía cuando era un frozenset a secas (D-REQ-2). Lo que cambió es la forma: el DTO permitió que otro paso necesitara más sin obligar a éste a enterarse.

emit

emit(event)

Permite pasar el step como AuditSink si un motor futuro lo requiere.

execute

execute(study, rng)

Ejecuta report determinístico sin consumir rng y publica tres artefactos.

Datasets y presets (helpers)

Utilidades para el quickstart y la UI: materialización determinista de datasets sintéticos, ingesta de uploads y el config F1 curado (standard_preset).

materialize

materialize(dataset_id, *, workdir)

Materializa un dataset a parquet determinista bajo workdir y lo cachea.

Deja además su perfil de columnas al lado (D-PERF-1), igual que :func:ingest_upload con un archivo subido: los datasets del catálogo no tienen por qué ser los únicos sobre los que el preflight no puede avisar de una columna identificador. Aquí también sale gratis —el generador ya devuelve el DataFrame—, y en la rama de caché lo repone :func:_asegurar_perfil.

Parameters:

Name Type Description Default
dataset_id str

Identificador del dataset. Un id uploaded_<token> resuelve el parquet ya materializado por :func:ingest_upload; en otro caso es la clave del registro sintético. Uno desconocido (o un upload no encontrado) levanta UiDatasetError.

required
workdir Path

Directorio de trabajo local; el parquet vive en workdir/datasets/<id>.parquet.

required

Returns:

Type Description
Path

Ruta del parquet materializado (o el cacheado si ya existía).

Raises:

Type Description
UiDatasetError

Si el dataset_id es desconocido, un upload no está materializado, o la ruta escaparía del workdir (path traversal).

list_datasets

list_datasets()

Devuelve el catálogo estable de datasets sintéticos.

Returns:

Type Description
list of dict

Un descriptor por dataset con id/name/description/columns/ index_columns/n_rows. Cada entrada de las dos listas trae name/dtype/ role y, desde D-COL-7, values con sus valores ofrecibles. El orden es estable (orden de inserción del registro), de modo que el listado no cambia entre corridas.

``index_columns`` va **aparte** desde D-PRO-1: el índice no es una columna, y publicarlo dentro
de ``columns`` hacía que la interfaz lo ofreciera donde el motor no puede leerlo. Un campo con
``column_role: "index"`` ofrece esta lista; uno con ``"input"``, la otra.
No depende del ``workdir``: estos datasets son sintéticos deterministas, así que sus valores
son una propiedad del catálogo y no de una materialización concreta.

ingest_upload

ingest_upload(
    content,
    filename,
    *,
    workdir,
    max_bytes=None,
    artifact=None,
)

Ingesta un dataset propio subido y lo materializa a parquet canónico bajo workdir.

Valida tamaño/formato, lee el archivo con pandas según su extensión (.csv/.xlsx/ .parquet) y lo materializa en workdir/datasets/uploaded_<token>.parquet (token = sha256 del contenido: determinista ⇒ el mismo archivo reusa su parquet cacheado). Devuelve el dataset_id más un preview de columnas. Es domain-agnostic: no importa bayesrisk.data; el cableado de data.load.source ocurre luego en :func:bayesrisk.ui.routes.run_pipeline, dejando intacta la byte-identidad del config canónico (SDD-23 §9, §11).

Parameters:

Name Type Description Default
content bytes

Bytes crudos del archivo subido.

required
filename str

Nombre original; su sufijo (.csv/.xlsx/.parquet) determina el lector pandas.

required
workdir Path

Directorio de trabajo local; el parquet vive en workdir/datasets/uploaded_<token>.

required

Returns:

Type Description
dict

{dataset_id, name, n_rows, columns} con columns = lista de {name, dtype}.

Raises:

Type Description
UiDatasetError

Si el archivo está vacío, supera max_bytes, su formato no está admitido, no se puede leer con pandas o no contiene filas/columnas de datos.

standard_preset

standard_preset()

Devuelve el descriptor del preset estándar F1 (config curado + dataset recomendado).

Returns:

Type Description
dict

{id, name, description, config, dataset_id}: un config F1 completo y JSON-able (copia defensiva, no el literal compartido) alineado a las columnas del dataset sintético consumo_comportamiento. El config valida con BayesRiskConfig.model_validate y corre end-to-end produciendo un scorecard; dataset_id es el dataset recomendado para materializar y ejecutar la corrida (SDD-23 §3.2/§5).

Extras opcionales

Introspección de extras instalados e imports perezosos con error accionable cuando falta una dependencia opcional.

has_extra

has_extra(extra, *modules)

Devuelve True si todos los modules del extra están importables (sin levantar).

require_extra

require_extra(extra, *modules)

Importa y devuelve los módulos de un extra; si falta uno, levanta MissingDependencyError.

Parameters:

Name Type Description Default
extra str

Nombre del extra (clave de [project.optional-dependencies]), usado en el mensaje de instalación.

required
*modules str

Nombres de módulos importables a resolver (p. ej. "xgboost").

()

Returns:

Type Description
tuple of module

Los módulos importados, en el mismo orden.

Raises:

Type Description
MissingDependencyError

Si alguno de los módulos no se puede importar.

Examples:

>>> xgb, = require_extra("xgboost", "xgboost")