Model card (autodoc)¶

Assembles the canonical multi-section ModelCard JSON consumed by the backend DOCX / HTML / PDF renderer. See the Evaluation & trust guide.

`build_model_card`¶

build_model_card ¶

build_model_card(
    profile: "ProfilingResult",
    *,
    fitted: Any | None = None,
    dataset_meta: Any | None = None,
    diagnostics: Any | None = None,
    drift_report: "PSIResult | None" = None,
    leakage_report: "LeakageReport | None" = None,
    trust_summary: "TrustSummary | None" = None,
    usecase: Any | None = None,
    annotations: Mapping[str, CardAnnotation] | None = None
) -> ModelCard

Assemble a :class:ModelCard from a fitted :class:ProfilingResult.

Pure science layer — no I/O, no caching, no backend specifics. Sections whose underlying artefact is missing surface as {"available": False} so the renderer in backend_changes_for_ui.md §5.5 can hide the row gracefully.

Parameters:

Name	Type	Description	Default
`profile`	`'ProfilingResult'`	The :class:`parleml_mli.ProfilingResult` to describe. Carries every first-party artefact (model_evaluation_, rules_, archetypes, error_analysis_, explanations_, eda_) the Model Card surfaces. Its in-memory narration slots are never read — AI-written text comes only from `annotations`.	required
`fitted`	`Any \| None`	Optional deployable artefact — a `FittedPipeline` instance (or any duck-typed object exposing `classes_` / `result` / `dfe` / `calibration_source` / `thresholds` / `version` / `dataset_name`). `None` is supported (the library §I6 predictions-only branch); the Final pipeline section then surfaces `{"available": False}`.	`None`
`dataset_meta`	`Any \| None`	Optional dataset metadata satisfying the :class:`~parleml_mli.autodoc.DatasetMetaLike` protocol — plain `dict` / SQLite row / backend dataclass all accepted. `None` degrades the cover + overview blocks to best-effort values pulled from `profile` and `fitted`.	`None`
`diagnostics`	`Any \| None`	Optional diagnostics payload carrying the Optuna leaderboard and the list of families tried (any object exposing `leaderboard` / `families_tried` attributes or keys). `None` leaves those rows empty in the Algorithm selection section.	`None`
`drift_report`	`'PSIResult \| None'`	Optional :class:`parleml_mli.explanations.drift.PSIResult` override. Defaults to `profile.explanations_.psi`.	`None`
`leakage_report`	`'LeakageReport \| None'`	Optional :class:`parleml_mli.eda.leakage.LeakageReport` override. Defaults to `profile.eda_.leakage_report`.	`None`
`trust_summary`	`'TrustSummary \| None'`	Optional :class:`parleml_mli.trust.TrustSummary` — when supplied, its `to_dict()` payload is embedded under `ModelCard.trust_summary` and its tiles seed the Recommendations section.	`None`
`usecase`	`Any \| None`	Optional governance metadata satisfying the :class:`~parleml_mli.autodoc.UseCaseGovernanceLike` protocol — drives the cover signoffs block + the overview `governance` slot.	`None`
`annotations`	`Mapping[str, CardAnnotation] \| None`	AI-written text the host attaches, keyed `"explain.narration"` (the dict :func:`parleml_mli.reporting.narrate_result` returns — the executive summary and the per-class narrations) and `"explain.fields"` (`{"fields": {column: {"label", "description"}}}` — the top features' descriptions). Each section that prints one carries its label, and :attr:`~ModelCard.ai_written` lists them. `None` — or a missing key — leaves that text to the deterministic templates.	`None`

Returns:

Type	Description
`ModelCard`	The canonical Model Card intermediate JSON (eleven content sections enumerated by :data:`~parleml_mli.autodoc.MODEL_CARD_SECTIONS` plus :attr:`~ModelCard.trust_summary`, :attr:`~ModelCard.provenance`, and :attr:`~ModelCard.schema_version`). The AutoDoc renderer (`backend_changes_for_ui.md` §5.5) consumes :meth:`ModelCard.to_dict` verbatim across HTML / DOCX / PDF outputs.

`ModelCard`¶

ModelCard `dataclass` ¶

ModelCard(
    cover: dict[str, Any] = dict(),
    executive_summary: str = "",
    executive_summary_label: str | None = None,
    overview: dict[str, Any] = dict(),
    data_quality: dict[str, Any] = dict(),
    feature_engineering: dict[str, Any] = dict(),
    algorithm_selection: dict[str, Any] = dict(),
    final_pipeline: dict[str, Any] = dict(),
    scores: dict[str, Any] = dict(),
    interpretability: dict[str, Any] = dict(),
    drift: dict[str, Any] = dict(),
    assumptions_limitations: dict[str, Any] = dict(),
    monitoring_plan: dict[str, Any] = dict(),
    governance_signoff: dict[str, Any] = dict(),
    recommendations: list[str] = list(),
    ai_written: list[dict[str, str]] = list(),
    figures: list[dict[str, Any]] = list(),
    trust_summary: dict[str, Any] | None = None,
    provenance: dict[str, Any] = dict(),
    schema_version: int = AUTODOC_SCHEMA_VERSION,
)

Canonical Model Card intermediate JSON.

Holds the content sections enumerated by :data:MODEL_CARD_SECTIONS (cover, executive summary, overview, data quality, feature engineering, algorithm selection, final pipeline, scores, interpretability, drift, assumptions & limitations, monitoring plan, governance & sign-off, recommendations) plus three scaffolding fields (:attr:trust_summary, :attr:provenance, :attr:schema_version).

Section order mirrors the AutoDoc template specification in backend_changes_for_ui.md §17 — the renderer iterates :data:MODEL_CARD_SECTIONS to lay sections out deterministically. Every nested value is JSON-clean (plain dict / list / str / int / float / bool / None) so the whole instance round-trips through :func:json.dumps without custom encoders.

Attributes:

Name	Type	Description
`cover`	`dict[str, Any]`	`{name, version, owner, date, signoffs, usecase_*}` — the title-page block. The release the model was approved under (its stage, risk level, operating point, approver) is added by the caller that holds the release record.
`executive_summary`	`str`	Plain-English one-paragraph narrative — the host's `"explain.narration"` annotation when attached, else a deterministic template (with the trust summary headline when one is supplied).
`executive_summary_label`	`str \| None`	The annotation's label (e.g. `"AI-written · Claude Code · haiku · 8 Oct"`) when :attr:`executive_summary` is AI-written; `None` for the template.
`overview`	`dict[str, Any]`	`{dataset, target, dials, runtime, task_type, n_classes, decision_threshold, governance, ...}` — what was modelled and how; `governance.sensitive_attributes` are the features the fairness report measured.
`data_quality`	`dict[str, Any]`	EDA alerts + missingness + duplicates + leakage findings.
`feature_engineering`	`dict[str, Any]`	`{n_features_raw, n_features_engineered, top_features, encoders, ...}` — encoder pipeline introspection.
`algorithm_selection`	`dict[str, Any]`	`{final_model, families_tried, ...}` — best-effort Optuna leaderboard surfaced when `diagnostics` carries it; otherwise the final-model class + hyperparameters.
`final_pipeline`	`dict[str, Any]`	`{model_class, calibration_source, decision_threshold, thresholds, ...}` — the deployed artefact.
`scores`	`dict[str, Any]`	`{per_split: {metric: value}, calibration: {ece, brier}, baselines: {...}}` — every metric `ModelEvaluationResult` publishes, plus the cost-matrix lens when supplied.
`interpretability`	`dict[str, Any]`	`{archetypes, top_rules, top_pdps, fairness, ...}` — the Explain page's headline artefacts compressed into the report.
`drift`	`dict[str, Any]`	`{by_feature, top_features, tier_counts, ...}` — the §3.21 Trust Summary's drift tile expanded out.
`assumptions_limitations`	`dict[str, Any]`	`{evaluation_basis, items, residual_risk}` — synthesized caveats (single-split evaluation, drift / leakage / imbalance flags, surrogate-fidelity gap) plus the residual-risk statement.
`monitoring_plan`	`dict[str, Any]`	`{items}` — synthesized monitoring recommendations keyed off the PSI / trust thresholds and the deployed decision threshold.
`governance_signoff`	`dict[str, Any]`	`{human_oversight, signoff}` — the deployed operating point + captured human-oversight governance fields, and either the recorded sign-offs or an audit-ready sign-off template.
`recommendations`	`list[str]`	Plain-English warnings — one entry per high-severity leakage finding, fairness flag, red trust tile, or significant drift.
`ai_written`	`list[dict[str, str]]`	One `{"section", "label"}` per section that printed AI-written text (`executive_summary` / `feature_engineering` / `interpretability`); empty when the card has none.
`figures`	`list[dict[str, Any]]`	Embedded charts attached by the backend renderer — an ordered list of `{id, section, title, caption, figure}` dicts where `figure` is a Plotly `{"data", "layout"}` payload. The library leaves this empty (the science layer does not plot); the backend's chart service populates it so the AutoDoc preview / HTML / DOCX surfaces can render figures next to their section.
`trust_summary`	`dict[str, Any] \| None`	Optional embedded :class:`parleml_mli.trust.TrustSummary` dict for the renderer's hero block. Lifted via :meth:`parleml_mli.trust.TrustSummary.to_dict`; `None` when no trust artefact was supplied.
`provenance`	`dict[str, Any]`	Library / artefact / dataset versions so the regulator can reconstruct exactly which code produced the doc.
`schema_version`	`int`	Bumped on any wire-shape change (mirrors :data:`AUTODOC_SCHEMA_VERSION`).

to_dict ¶

to_dict() -> dict[str, Any]

JSON-clean dict suitable for the FastAPI response body.

`CardAnnotation`¶

AI-written text the host attaches to a card, keyed "explain.narration" / "explain.fields". See AI-written narration.

CardAnnotation `dataclass` ¶

CardAnnotation(value: Mapping[str, Any], label: str)

AI-written text the host attaches to a model card, and the label every reader sees.

Section ordering¶

MODEL_CARD_SECTIONS is the canonical, deterministic ordering the renderer iterates across HTML / DOCX / PDF.

MODEL_CARD_SECTIONS `module-attribute` ¶

MODEL_CARD_SECTIONS: tuple[str, ...] = (
    "cover",
    "executive_summary",
    "overview",
    "data_quality",
    "feature_engineering",
    "algorithm_selection",
    "final_pipeline",
    "scores",
    "interpretability",
    "drift",
    "assumptions_limitations",
    "monitoring_plan",
    "governance_signoff",
    "recommendations",
)

Canonical ordering of the Model Card sections — matches the AutoDoc template structure in backend_changes_for_ui.md §17. The renderer iterates this tuple to keep section ordering deterministic across HTML / DOCX / PDF outputs.

The three governance sections (assumptions_limitations / monitoring_plan / governance_signoff) sit just before recommendations so the document reads evidence → caveats → monitoring → sign-off → actions.

Backend-supplied input protocols¶

Duck-typed contracts build_model_card reads off its optional dataset_meta / use_case_governance arguments — the backend's dataclasses, SQLite rows, or plain dicts all satisfy them.

DatasetMetaLike ¶

Bases: Protocol

Minimum surface :func:build_model_card reads off dataset_meta.

The backend's DatasetMeta dataclass / SQLite row / plain dict all satisfy this contract via attribute access or mapping-style lookup — :func:parleml_mli.autodoc._sections._get normalises both.

Attributes:

Name	Type	Description
`name`	`str`	Dataset display name (`"fraud_2026_q1"`).
`version`	`str \| None`	Optional dataset version (catalog `v3`, hash, semver).
`n_rows`	`int`	Total row count of the training matrix.
`n_columns`	`int`	Total column count of the raw (pre-FE) frame.
`target`	`str \| None`	Target column name. `None` for unsupervised use-cases.
`target_rate`	`float \| None`	Positive-class rate (binary) / mean (regression) / most-frequent rate (multiclass). `None` when unknown.
`fingerprint`	`str \| None`	Stable content / schema hash for reproducibility. `None` when the backend did not compute one.

UseCaseGovernanceLike ¶

Bases: Protocol

Minimum surface :func:build_model_card reads off usecase.

Mirrors the /api/usecases payload documented in backend_changes_for_ui.md §3.0. All fields optional; the builder degrades to a generic "no use-case bound" cover when usecase is None.

A use case's stage and risk level are not read: they describe the use case, not a model built in it. Nor is a typed list of sensitive attributes — the card's are the ones the run's fairness report measured.

Model card (autodoc)¶

build_model_card¶