| # Adding an AS² instantiation |
|
|
| An instantiation is a Hydra configuration plus the task-specific implementations |
| it selects. Visual Sudoku is the bundled example. MNIST Addition and CLEVR-Hans |
| are future targets, not runnable options in this release. |
|
|
| The shared commands dispatch by capability, with no benchmark branches: |
|
|
| ```bash |
| uv run --locked softasp-train instantiation=your_task |
| uv run --locked softasp-train-scratch instantiation=your_task |
| uv run --locked softasp-predict instantiation=your_task |
| uv run --locked softasp-evaluate instantiation=your_task |
| ``` |
|
|
| These commands require your implementation and configuration to exist. Place |
| `your_task.yaml` in `configs/instantiation/`, or supply an additional Hydra config |
| search directory containing that group. Install your provider module in the same |
| uv environment. No shared CLI or framework source edits are needed to select an |
| implemented instantiation. |
|
|
| ## Configuration contract |
|
|
| Use `# @package _global_` so the instantiation can compose dataset, preprocessing, |
| model, trainer, evaluator, paths and any workflow-specific sections. The bundled |
| [`sudoku.yaml`](../configs/instantiation/sudoku.yaml) is a complete working example. |
|
|
| An extension configuration follows this structure (provider names are illustrative): |
|
|
| ```yaml |
| # @package _global_ |
| defaults: |
| - /trainer: default |
| - _self_ |
| |
| dataset: |
| name: your_task |
| # Dataset parameters, splits, paths and preprocessing choices go here. |
| model: |
| name: your_model |
| pretrained_from: null |
| freeze_backbone_epochs: 0 |
| params: {} |
| evaluator: |
| checkpoint: null |
| metrics: [accuracy] |
| |
| instantiation: |
| name: your_task |
| version: 1 |
| constraints: |
| _target_: your_package.constraints.ConstraintLoss |
| providers: |
| dataset: {_target_: your_package.providers.DatasetProvider} |
| model: {_target_: your_package.providers.ModelProvider} |
| metrics: {_target_: your_package.providers.MetricsProvider} |
| prediction: {_target_: your_package.providers.PredictionProvider} |
| evaluation: {_target_: your_package.providers.EvaluationProvider} |
| workflow: {_target_: your_package.providers.WorkflowProvider} |
| ``` |
|
|
| Add hyperparameters, data identities, paths, network composition, objective |
| weights, evidence policies, input/output settings and workflow stages needed by |
| your task. Use the existing trainer schema and configuration groups; unknown |
| trainer fields are not arbitrary model parameters. Model-specific settings belong |
| under `model.params` or an instantiation-owned section. The top-level `paths` |
| group is composed by the common training configurations; prediction configurations |
| also compose it explicitly. `predict` supplies `checkpoint`, `input`, `output` |
| and `device` for the bundled adapter; another adapter may define different inputs. |
|
|
| ## Provider methods |
|
|
| Hydra constructs each provider from its `_target_` and constructor parameters. |
| Keep provider construction free of stochastic model initialization; build models |
| inside `prepare` or `build`, after the training entrypoint applies its seed policy. |
|
|
| | Provider | Required methods | Contract | |
| |---|---|---| |
| | Dataset | `build(cfg)` | Return `(training_dataset, validation_dataset)`; handle task-specific preparation/selection and identity validation. | |
| | Model | `prepare(cfg)`, `build(cfg)` | `prepare` returns a model or `None` before dataset construction; `build` constructs after datasets if needed. Bind configured constraints/objectives here. | |
| | Model inference | `load(cfg)` | Required by `softasp.inference.load_model(cfg)`; validate and strictly load the selected checkpoint. | |
| | Metrics | `build(cfg)` | Return an evaluator with `evaluate(model, loader, device) -> dict[str, float]`. | |
| | Prediction | `run(cfg)` | Return a JSON-serializable result. The common CLI writes `cfg.output` without overwriting an existing file. Never use solution labels. | |
| | Evaluation | `run(cfg)` | Score configured splits and write task-specific reports/provenance; return a result dictionary. | |
| | Workflow | `run(cfg)` | Execute the task's full workflow and return its result/artifact path. It may call shared `run_training(cfg)`. | |
|
|
| Training datasets yield dictionaries of tensors accepted by the shared loader. |
| Models implement `BaseSoftASPModel.forward(batch)` with a differentiable `loss` |
| and appropriate logits or predictions. The standard evaluator uses `labels` and |
| `logits`/`predictions`; supply a custom evaluator for other target/output contracts. |
| For freezing or gradient ramps, expose the relevant module through |
| `get_backbone()`. A model without a backbone returns `None`. |
|
|
| ## Reusable components and task-specific constraints |
|
|
| `softasp_solver.components.reasoning.AS2Network` composes an encoder, concept head, |
| probability projection, attention module, task head and optional structure module. |
| Its input encoder produces `(batch, positions, features)`. A task head may return |
| per-position outputs or pool into a classification output. Images, 81 positions, |
| nine symbols, Sudoku masks and per-cell predictions are not framework requirements. |
|
|
| The `components` package also supplies explicit evidence policies and structural |
| embeddings; `constraints` supplies shared operators and fixed-point residuals. |
| An instantiation may reuse these components or provide another differentiable |
| implementation appropriate to its declarative constraints. |
|
|
| Each instantiation owns its constraint specification and implementation. Sudoku |
| keeps both in `softasp_solver.sudoku.constraints`, with its training objectives |
| in `softasp_solver.sudoku.objective`. Changing specification text alone does not |
| change the numerical implementation: there is no automatic ASP compiler. |
|
|
| ## Checkpoints and verification |
|
|
| Training saves the resolved configuration, including instantiation identity and |
| providers. The common resume path validates instantiation/model identity and |
| constraint/network configuration before restoring state. Prediction/evaluation |
| providers must call the shared checkpoint validation helpers and load state |
| strictly; the bundled Sudoku providers do so. Only the explicitly recognized |
| legacy Sudoku inference checkpoint is accepted without instantiation metadata. |
|
|
| Test your adapter through all four commands, checkpoint round-trip, incompatible |
| identity rejection, and label-free prediction. The release's development checks |
| exercise a non-image, pooled-head AS² fixture with its own constraint residual |
| through the same entrypoints. That fixture is an interface test, not an additional |
| scientific benchmark. Dataset downloading and from-scratch stage order belong |
| to the instantiation; the common framework does not impose Sudoku's two-stage recipe. |
|
|
