infer.resolve¶

def resolve_model_dir(
    model_dir: str | None,
    models_dir: Path,
    policy: SelectionPolicy | None = None,
) -> Path:
    """Resolve the model directory for inference.

    .. deprecated::
        Use :func:`resolve_inference_config` instead.  This function
        only resolves the model bundle path; it does not load the
        calibrator store or reject threshold from the inference policy.

    Resolution precedence:

    1. If *model_dir* is provided, validate that it exists and return it.
    2. Otherwise, delegate to :func:`~taskclf.model_registry.resolve_active_model`
       which reads ``active.json`` or falls back to best-model selection.
    3. If no eligible model is found, raise :class:`ModelResolutionError`
       with a descriptive message including exclusion reasons.

    Args:
        model_dir: Explicit ``--model-dir`` value from CLI, or ``None``.
        models_dir: Base directory containing promoted model bundles.
        policy: Selection policy override (defaults to policy v1).

    Returns:
        Path to the resolved model bundle directory.

    Raises:
        ModelResolutionError: When no model can be resolved.
    """
    if model_dir is not None:
        path = Path(model_dir)
        if not path.is_dir():
            raise ModelResolutionError(
                f"Explicit --model-dir does not exist: {model_dir}"
            )
        return path

    if not models_dir.is_dir():
        raise ModelResolutionError(
            f"Models directory does not exist: {models_dir}. "
            "Provide --model-dir explicitly or train a model first."
        )

    bundle, report = resolve_active_model(models_dir, policy)

    if bundle is not None:
        logger.info("Resolved model: %s", bundle.path)
        return bundle.path

    lines = [
        f"No eligible model found in {models_dir}.",
        "Provide --model-dir explicitly or train a compatible model.",
    ]
    if report is not None and report.excluded:
        lines.append("Excluded bundles:")
        for rec in report.excluded:
            lines.append(f"  - {rec.model_id}: {rec.reason}")
    raise ModelResolutionError("\n".join(lines), report=report)

def resolve_inference_config(
    models_dir: Path,
    *,
    model_dir_override: str | None = None,
    reject_threshold_override: float | None = None,
    calibrator_store_override: Path | None = None,
    calibrator_path_override: Path | None = None,
) -> ResolvedInferenceConfig:
    """Resolve the full inference configuration from policy or fallback.

    Resolution precedence:

    1. Explicit *model_dir_override* — bypasses policy; uses override
       flags for threshold and calibrator.
    2. ``models/inference_policy.json`` — loads model, calibrator store,
       and threshold from the policy.  Explicit overrides still take
       precedence for individual fields.
    3. ``models/active.json`` + code defaults — deprecated legacy
       fallback.
    4. Best-model selection + code defaults — no-config fallback.

    Args:
        models_dir: The ``models/`` directory.
        model_dir_override: Explicit ``--model-dir`` value (takes
            highest precedence).
        reject_threshold_override: Explicit threshold that overrides
            the policy value.
        calibrator_store_override: Explicit calibrator store path that
            overrides the policy value.
        calibrator_path_override: Explicit single-calibrator JSON path
            (lowest calibrator precedence).

    Returns:
        A fully resolved :class:`ResolvedInferenceConfig`.

    Raises:
        ModelResolutionError: When no model can be resolved.
    """
    policy: InferencePolicy | None = None
    model_path: Path | None = None
    reject_threshold: float = DEFAULT_REJECT_THRESHOLD
    calibrator: Calibrator = IdentityCalibrator()
    cal_store: CalibratorStore | None = None

    if model_dir_override is not None:
        model_path = Path(model_dir_override)
        if not model_path.is_dir():
            raise ModelResolutionError(
                f"Explicit --model-dir does not exist: {model_dir_override}"
            )
    else:
        policy = load_inference_policy(models_dir)
        if policy is not None:
            base = models_dir.parent
            model_path = base / policy.model_dir
            if not model_path.is_dir():
                logger.warning(
                    "Policy model_dir %s does not exist; falling back",
                    policy.model_dir,
                )
                policy = None
                model_path = None

        if model_path is None:
            if policy is not None:
                logger.warning("Policy references missing model; falling back")
                policy = None
            logger.warning(
                "No inference policy found; falling back to active.json "
                "resolution.  Create a policy with 'taskclf policy create' "
                "or 'taskclf train tune-reject --write-policy'."
            )
            model_path = resolve_model_dir(None, models_dir)

    per_user_thresholds: dict[str, float] | None = None
    if policy is not None:
        reject_threshold = policy.reject_threshold
        per_user_thresholds = policy.per_user_reject_thresholds

    # Load calibrator store
    if calibrator_store_override is not None:
        cal_store = load_calibrator_store(calibrator_store_override)
    elif policy is not None and policy.calibrator_store_dir is not None:
        store_path = models_dir.parent / policy.calibrator_store_dir
        if store_path.is_dir():
            cal_store = load_calibrator_store(store_path)
        else:
            logger.warning(
                "Policy calibrator_store_dir %s does not exist; using identity",
                policy.calibrator_store_dir,
            )

    if calibrator_path_override is not None and cal_store is None:
        calibrator = load_calibrator(calibrator_path_override)

    if reject_threshold_override is not None:
        reject_threshold = reject_threshold_override

    model, metadata, cat_encoders = load_model_bundle(model_path)
    logger.info(
        "Resolved inference config: model=%s schema=%s threshold=%.4f "
        "calibrator_store=%s policy=%s",
        model_path.name,
        metadata.schema_hash,
        reject_threshold,
        "yes" if cal_store is not None else "no",
        "yes" if policy is not None else "legacy",
    )

    return ResolvedInferenceConfig(
        model=model,
        metadata=metadata,
        cat_encoders=cat_encoders,
        reject_threshold=reject_threshold,
        calibrator=calibrator,
        calibrator_store=cal_store,
        policy=policy,
        per_user_reject_thresholds=per_user_thresholds,
    )