---

name: setup description: "Install YiVal, inspect CLI commands, create/validate experiment YAML, and choose dataset/config fields." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

YiVal setup and configuration

Use this sub-skill when the user needs to install YiVal, inspect yival CLI behavior, initialize or validate YAML, choose dataset source fields, or debug early config loading before an experiment run.

Read first

• CLI reference: subcommands, flags, and defaults.
• Config quickstart: minimal YAML shapes for dataset, machine-generated, and user-input workflows.
• Data formats: CSV and Hugging Face reader details.
• Setup troubleshooting: setup-specific errors.

Useful bundled helper:

• python sub-skills/setup/scripts/build_config_template.py --help builds a starter YAML through YiVal's own config-generation utility after importing built-ins.

Installation checklist

1. Use Python >=3.10,<3.13.
2. Install YiVal in the target environment:
   • from PyPI/package index: python -m pip install yival
   • from a source checkout: python -m pip install -e .
3. Install optional trainer extras only for approved fine-tuning: python -m pip install 'yival[trainers]' or python -m pip install -e '.[trainers]'.
4. If CLI import errors mention pkg_resources, run python -m pip install 'setuptools<81'.
5. Confirm the environment from the skill root: python scripts/check_install.py --check-cli.

CLI setup routes

Task	Command shape
Show root help	python -m yival --help or yival --help
Generate a template	yival init --config_path config.yml --function my_module.my_func --source_type dataset ...
Validate YAML	yival validate config.yml
Run a config	yival run config.yml --output_path results.pkl
Try packaged demos	yival demo --qa_expected_results, yival demo --basic_interactive, yival demo --auto_prompts
Interactive auto-config	yival gen or yival task

Important defaults:

• yival run --display is an action="store_true" flag with default True; CLI runs normally display Dash results unless you call ExperimentRunner.run(display=False) programmatically.
• yival bot defaults to interactive=True and display=False.
• yival demo copies a packaged demo config into the current working directory before running it.

YAML minimum contract

Every useful config needs:

description: short experiment description
custom_function: module.path.function_name
dataset:
  source_type: dataset

Then add fields according to source type:

• source_type: dataset: include file_path and reader.
• source_type: machine_generated: include data_generators.
• source_type: user_input: normally no file path; used for interactive UI.

For prompt/model comparisons, also add variations and one or more evaluators.

Decision points

• If rows already exist, prefer source_type: dataset with csv_reader and a small fixture first.
• If examples must be generated from a prompt or document, route to prompt-automation before running provider-backed generation.
• If the task is mostly metric/selector design, route to evaluation-optimization.
• If YAML contains custom_* sections, route to custom-components to verify class/config paths and registry keys.
• For no-network smoke tests, run the root helper python scripts/write_minimal_experiment.py --run from the skill root.

Validation workflow

1. Load or generate YAML.
2. Check custom_function importability. For local modules, ensure the module's directory is on PYTHONPATH or run from a working directory where it imports directly.
3. Check dataset row keys match the custom function's parameters except state.
4. Check variation names match the StringWrapper(name=...) calls in the custom function.
5. Check evaluator/reader/generator ids exist in registry overview.
6. Run yival validate config.yml; if it passes, run a tiny dataset before scaling up.

Handoff to running

After setup is valid, read run for execution, result pickle names, Dash/interactive behavior, and programmatic runner choices.