Jinkō Model SDK Workflows
Use this skill for technical model construction and editing through the SDK. Keep the scope on SDK mechanics and model validity, not biological plausibility. Initialize the connection with jinko-sdk-setup first.
PREREQUISITE: This skill needs an initialized jinko-sdk connection and an
SDK satisfying its metadata.requires_sdk range. Run the jinko-sdk-setup skill
(../jinko-sdk-setup/SKILL.md) and proceed only once its check passes. If that
skill is not found, install it from novainsilico/jinko-skills.
Required Workflow
- If a model was already supplied, prefer editing it over creating a new one. Create one only when needed, in a dedicated folder, with
client.create_empty_model().
- Retrieve the model, inspect its components, tags, units, solving options, and diagnostics before proposing edits. Inspect the unit-checking mode with
model.get_unit_check().
- Set the unit-checking mode with
model.set_unit_check("UnitCheckAndConvertAllSpeciesToExtentUnits"). Do not select another mode unless a human explicitly directs it after the consequences are explained.
- Give every directly declared numeric value a unit: numeric parameter formulas, compartment volumes, and species initial conditions. A parameter whose value is derived from an expression may omit its declared unit when the expression determines it. Validate non-trivial units against
references/units_static_info.json and diagnostics.
- Attach the built-in platform tags before considering the model complete:
i::vpop for inputs that vary across virtual patients.i::protocol for inputs that vary across protocol arms or scenarios.- One evidence-backed source tag for each applicable value-bearing input:
s::knowledge, s::arbitrary, or s::to-calibrate. Leave an uncertain input untagged and report it for review. Never assign s::calibrated during construction; it records an accepted calibration result.
output for important time-series outputs to plot or calibrate against.
- Use high-level SDK methods and
model.components.batch(version="...") for related component changes. The platform tags above already exist; do not recreate them. Create declarations only for other, custom tags.
- Re-fetch the model, require no error diagnostics, and run
simple_solve() for representative output components. For events, verify the expected pre-/post-event change.
Use scripts/create_minimal_model.py, and the SDK's python -m jinko.cli.tag_model_components and python -m jinko.cli.validate_model_readiness, rather than long ad-hoc snippets. Scripts are dry-run by default and mutate only with --apply.
For transparent ISO 8601 duration conversions, use from jinko.iso8601 import Duration, for example Duration.parse("P1M").to_timedelta(). Solving times accept timedelta or ISO strings: model.set_solving_times(t_max=timedelta(days=28), t_step="P1D", additional_periods=[{"t_max": "P7D", "t_step": timedelta(hours=1)}]).
Reference Routing
- Read
references/model-components.md for component batching, tags, events, formulas, and algebraic rules.
- Read
references/unit_docs.md for unit semantics and conversion behavior.
- Read
references/model-validation.md for diagnostics and readiness checks.
1---2name: jinko-model3description: Build or edit a Jinkō computational model (QSP/PK-PD) via the jinko-sdk: parameters, categorical parameters, compartments, species, ODEs, reactions, dosing events, algebraic rules, baseline checks, solving options, units, and component tags. Use this skill whenever the user wants to create a model from scratch, create an empty model, edit an existing model, add or modify components, apply input/source/output tags, configure unit checking, define model-level dosing events, validate diagnostics, or debug model sanity or simple_solve errors. Prefer editing existing models over recreating them. Do not use this skill for running trials; use jinko-trial for trial execution.4license: MIT5---67# Jinkō Model SDK Workflows89Use this skill for technical model construction and editing through the SDK. Keep the scope on SDK mechanics and model validity, not biological plausibility. Initialize the connection with `jinko-sdk-setup` first.1011> **PREREQUISITE:** This skill needs an initialized `jinko-sdk` connection and an12> SDK satisfying its `metadata.requires_sdk` range. Run the `jinko-sdk-setup` skill13> (`../jinko-sdk-setup/SKILL.md`) and proceed only once its check passes. If that14> skill is not found, install it from `novainsilico/jinko-skills`.1516## Required Workflow17181. If a model was already supplied, prefer editing it over creating a new one. Create one only when needed, in a dedicated folder, with `client.create_empty_model()`.192. Retrieve the model, inspect its components, tags, units, solving options, and diagnostics before proposing edits. Inspect the unit-checking mode with `model.get_unit_check()`.203. Set the unit-checking mode with `model.set_unit_check("UnitCheckAndConvertAllSpeciesToExtentUnits")`. Do not select another mode unless a human explicitly directs it after the consequences are explained.214. Give every directly declared numeric value a unit: numeric parameter formulas, compartment volumes, and species initial conditions. A parameter whose value is derived from an expression may omit its declared unit when the expression determines it. Validate non-trivial units against `references/units_static_info.json` and diagnostics.225. Attach the built-in platform tags before considering the model complete:23 - `i::vpop` for inputs that vary across virtual patients.24 - `i::protocol` for inputs that vary across protocol arms or scenarios.25 - One evidence-backed source tag for each applicable value-bearing input: `s::knowledge`, `s::arbitrary`, or `s::to-calibrate`. Leave an uncertain input untagged and report it for review. Never assign `s::calibrated` during construction; it records an accepted calibration result.26 - `output` for important time-series outputs to plot or calibrate against.276. Use high-level SDK methods and `model.components.batch(version="...")` for related component changes. The platform tags above already exist; do not recreate them. Create declarations only for other, custom tags.287. Re-fetch the model, require no error diagnostics, and run `simple_solve()` for representative `output` components. For events, verify the expected pre-/post-event change.2930Use `scripts/create_minimal_model.py`, and the SDK's `python -m jinko.cli.tag_model_components` and `python -m jinko.cli.validate_model_readiness`, rather than long ad-hoc snippets. Scripts are dry-run by default and mutate only with `--apply`.3132For transparent ISO 8601 duration conversions, use `from jinko.iso8601 import Duration`, for example `Duration.parse("P1M").to_timedelta()`. Solving times accept `timedelta` or ISO strings: `model.set_solving_times(t_max=timedelta(days=28), t_step="P1D", additional_periods=[{"t_max": "P7D", "t_step": timedelta(hours=1)}])`.3334## Reference Routing3536- Read `references/model-components.md` for component batching, tags, events, formulas, and algebraic rules.37- Read `references/unit_docs.md` for unit semantics and conversion behavior.38- Read `references/model-validation.md` for diagnostics and readiness checks.
novainsilico