[Forge] Extend analysis framework to include model-building steps done coding:7 reasoning:6

[Forge] Extend analysis framework to include model-building steps

Goal

Currently, SciDEX analyses execute steps like data_retrieval, statistical_test, and visualization. This task adds model_building as a first-class analysis step type, enabling analyses to construct, train, and evaluate scientific models as part of their execution pipeline. Each model-building step produces a versioned model artifact.

Background

The Forge layer manages the scientific execution engine — tool registry, logging, and tool-augmented analysis. Analyses are defined as sequences of steps. Adding model building extends Forge from "analyze data" to "build understanding" — models encode hypotheses about mechanisms and can be tested, refined, and compared.

Design

AnalysisModelSpec

New step type specification embedded in analysis definitions:

{
  "step_type": "model_building",
  "model_spec": {
    "model_family": "biophysical",
    "template": "ode_system",
    "input_datasets": ["dataset-allen_brain-SEA-AD"],
    "input_parameters_from_kg": true,
    "hyperparameters": {
      "solver_method": "RK45",
      "t_span": [0, 100],
      "fitting_method": "least_squares"
    },
    "evaluation_metrics": ["rmse", "aic", "parameter_sensitivity"],
    "output_artifact_type": "model"
  }
}

Execution Flow

Analysis engine encounters step_type="model_building"

Load the specified template (biophysical, deep_learning, or statistical)

Fetch input datasets from artifact registry

If input_parameters_from_kg: query KG for relevant parameters/rate constants

Execute template with hyperparameters

Evaluate model against metrics

Register output as versioned model artifact via register_model()

Pin all input artifact versions in analysis provenance

Create artifact_links: model derives_from dataset, analysis produces model

Integration with Existing Analysis Framework

• Add model_building to the valid step_type enum
• Add ModelBuildingStep handler in the analysis execution engine
• Model templates are pluggable — registered in the Forge tool registry
• Model outputs appear in analysis results alongside existing step outputs

Analysis Result Enhancement

{
  "analysis_id": "SDA-2026-04-05-xxx",
  "steps": [
    {"step_type": "data_retrieval", "status": "completed", "output": "..."},
    {"step_type": "model_building", "status": "completed", 
     "output": {
       "model_artifact_id": "model-biophys-microglia-v1",
       "evaluation": {"rmse": 0.023, "aic": -450},
       "parameter_sensitivity": {"k_phago": 0.85, "k_clear": 0.42}
     }},
    {"step_type": "visualization", "status": "completed", "output": "figure-tc-001"}
  ]
}

Acceptance Criteria

Dependencies

• a17-23-MODL0001 (model artifact type and register_model())

Dependents

• frg-mb-02-BIOP (biophysical template)
• frg-mb-03-DL01 (deep learning template)
• frg-mb-04-MREG (model registry integration)

Work Log

2026-04-26 06:30 UTC — Implementation (task:frg-mb-01-ANLX)

Changes made:

Created scidex/forge/analysis_steps.py (new file):

- StepType enum with values: data_retrieval, statistical_test, visualization, model_building
- AnalysisModelSpec dataclass with fields: model_family, template, input_datasets, input_parameters_from_kg, hyperparameters, evaluation_metrics, output_artifact_type, tests_hypothesis_id, analysis_id
- AnalysisModelSpec.validate() — validates model_family against {biophysical, deep_learning, statistical}
- AnalysisModelSpec.to_dict() / from_dict() — serialization
- StepResult dataclass — result of executing a step
- ModelBuildingStepHandler — executes model_building steps, registers models via register_model()
- execute_model_building_step() — top-level function for running model_building steps
- validate_analysis_steps() — validates a list of analysis steps

Updated scidex/forge/__init__.py — exports all analysis_steps public API

Created tests/test_analysis_steps.py (19 tests):

- TestStepType — enum values and validity checks
- TestAnalysisModelSpec — validation, roundtrip, all three model families
- TestStepResult — serialization
- TestModelBuildingStepHandler — initialization, framework mapping
- TestValidateAnalysisSteps — step validation
- TestExecuteModelBuildingStep — execution flow

Integration points:

• Uses scidex.atlas.artifact_registry.register_model() (from MODL0001 dependency)
• Uses scidex.atlas.artifact_registry.record_processing_step() for provenance
• Uses scidex.atlas.artifact_registry.get_artifact() to fetch input datasets
• Framework mapping: biophysical→scipy, deep_learning→pytorch, statistical→sklearn

Tests: 19 passed, all green

Note: KG parameter extraction (input_parameters_from_kg=true) is stubbed — actual KG integration would be done in dependent tasks (frg-mb-02-BIOP, frg-mb-03-DL01).