[REFACTOR] Resource preparation

[jeipollack]

Description of Refactoring/Improvement

This task extends the Resources class, introduced in #244, to prepare resources required by enabled quality control metrics when they are not supplied by the pipeline caller.

The current Resources.resolve() method identifies missing resources but raises NotImplementedError because resource preparation is not yet implemented. This task will implement the preparation step and integrate it into resource resolution.

Scope

• Add a prepare_resources() helper to the Resources class.
• Define how missing resource identifiers are mapped to their corresponding preparation mechanism.
• Prepare missing resources from the validated quality control configuration.
• Update Resources.resolve() to use prepare_resources() for resources not supplied by the caller.
• Preserve caller-provided resources without unnecessary preparation.
• Return a complete mapping of resources required by enabled quality metrics.
• Update unit tests for resource preparation and resolution.
• Update integration tests as appropriate.
• Update documentation and configuration examples if the preparation interface introduces user-visible configuration.

Design Considerations

Separation of resolution and preparation

Resources.resolve() should remain the public resource-management API. It should determine which resources are required, identify resources already supplied by the caller, and delegate preparation of missing resources to prepare_resources().

Conceptually:

required resources
       │
       ├── provided ───────────────→ resolved
       │
       └── missing ──→ prepare ────→ resolved

Configuration-driven preparation

Resource preparation should be based on the validated QualityControlConfig rather than requiring the caller to know how individual resources are constructed.

The resource configuration should therefore provide sufficient information to identify and prepare each required resource.

Caller-provided resources

Caller-provided resources take precedence over prepared resources.

Resources.resolve() first compares the resources required by enabled quality metrics with those supplied by the pipeline caller. Only resources identified as missing are passed to prepare_resources() for preparation.

This ensures that an already-supplied resource is never unnecessarily regenerated or replaced by a prepared resource.

Resource-specific preparation

Preparation mechanisms may differ between resource types. The design should avoid coupling Resources to the implementation details of every possible resource where practical, so that additional resource types can be introduced without substantially changing the resolution interface.

Missing and unavailable resources

The implementation should distinguish between:

• resources supplied by the caller;
• resources that are missing and can be prepared from configuration;
• resources that are required but cannot be prepared or otherwise resolved.

If an enabled metric requires a resource that cannot be resolved, the resource-resolution stage should raise a clear error identifying the unavailable resource(s), rather than silently skipping the metric.

Skipping an enabled metric because one of its required resources is unavailable is outside the scope of this task.

Validation

The implementation should continue to rely on the validated QualityControlConfig established by QualityControlConfigHandler. Resource preparation should not duplicate cross-section configuration validation already performed during configuration loading.

Out of Scope

• Determining whether the quality control pipeline should be run.
• Determining how the quality control pipeline is invoked by the CLI or workflow.
• Implementing individual quality metrics or rejection policies.
• Changing the quality control configuration model unless required to support resource preparation.

Acceptance Criteria

• Resources.resolve() can resolve all resources required by enabled metrics when they are either supplied by the caller or can be prepared from configuration.
• Caller-provided resources are reused rather than unnecessarily prepared.
• Missing resources are prepared through the resource preparation mechanism.
• Unresolvable required resources produce a clear error.
• Existing resource-resolution behaviour remains covered by tests.
• New resource-preparation behaviour is covered by unit tests.
• Relevant integration tests pass.

[jeipollack]

I am thinking about the second bullet: how missing resource identifiers are mapped to their corresponding preparation mechanism.

What I've come up with is to create a resource-family registry:

RESOURCE_PREPARERS = {
    "psf_models": run_inference_pipeline,
}

with the following processing flow:

required:
    "psf_models.standard"
          │
          ▼
Resources.resolve()
    missing = {"psf_models.standard"}
          │
          ▼
Resources.prepare_resources(missing, dataset)
          │
          ├── split identifier
          │     family = "psf_models"
          │     variant = "standard"
          │
          ├── look up configuration
          │     resources.available["psf_models"]["standard"]
          │
          ├── select preparer
          │     "psf_models" → run_inference_pipeline
          │
          └── run preparer with inference config + dataset
                         │
                         ▼
                  prepared PSF model
                         │
                         ▼
              "psf_models.standard"

Only resources identified as missing during resolution would be passed to prepare_resources(). Caller-provided resources therefore take precedence and are not unnecessarily prepared.

run_inference_pipeline needs an inference configuration file and the dataset. It doesn't need to know whether standard or oversampled PSFs are desired; that information can be managed by the resource preparation layer.

The API could be something like:

resolved_resources = resource_manager.resolve(
    provided_resources,
    dataset=dataset,
)

This avoids passing the dataset into the Resources constructor, keeping execution data separate from the resource manager's configuration state.

The precise implementation of the registry (module-level mapping, class attribute, or dedicated registry) can be figured out next.