jinko-model
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, import a model from an SBML, SimBiology XLSX, or Monolix file or a Monolix project, edit an existing model, add or modify components, apply input/source/output tags, configure unit checking, define model-level dosing events, combine two models and resolve their conflicts, 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.
How do I install this agent skill?
npx skills add https://github.com/novainsilico/jinko-skills --skill jinko-modelIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a technical implementation for managing Jinkō computational models using a specialized SDK. It follows security best practices by using safe AST parsing for mathematical formulas and relying on standard environment variables for authentication.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
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-sdkconnection and an SDK satisfying itsmetadata.requires_sdkrange. Run thejinko-sdk-setupskill (../jinko-sdk-setup/SKILL.md) and proceed only once its check passes. UseJINKO_API_KEYwhen it is set. Only without a key, callget_session_codeagain before this skill's own SDK process, because a session code can be exchanged only once. If that skill is not found, install it fromnovainsilico/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(). To import an SBML, SimBiology XLSX, or Monolix structural model file, useclient.create_model_from_file(). To import a Monolix project (.mlxtran), useclient.import_monolix_project(): it also creates a simple output set and a trial. To replace the content of an existing model from such a file, usemodel.replace_from_file(): it creates a new version and drops the component tags. An import may rename components, change units, or leave inputs without values: review the result like any other model with the steps below. -
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. Give a literal inside a formula its unit with
u(...), for example13.2 * u(L/h) * scale. A derived parameter may omit its declared unit only when it is not an output: declare the unit of everyoutputparameter, includingdimensionless, or results report the raw number in a composite unit. Validate non-trivial units againstreferences/units_static_info.jsonand diagnostics. Readreferences/unit-pitfalls.mdbefore building a model with non-substance states (volumes, cell counts, dimensionless) or literal physiological values. -
Attach the built-in platform tags before considering the model complete:
i::vpopfor inputs that vary across virtual patients.i::protocolfor inputs that vary across protocol arms or scenarios, including the dose amount, first dose time, dose interval, and number of doses of a dosing event.- One evidence-backed source tag for each applicable value-bearing input:
s::knowledge,s::arbitrary, ors::to-calibrate. Leave an uncertain input untagged and report it for review. Never assigns::calibratedduring construction; it records an accepted calibration result. outputfor important time-series outputs to plot or calibrate against.
Three of these decide whether the model is usable downstream, so check them across the whole model, not only per component. At least one component must carry
output, or nothing can be plotted, measured, or calibrated against: treat its absence as an error. No component carryingi::protocolmeans the model cannot be given protocol arms, and none carryingi::vpopmeans it cannot vary across virtual patients: report each as a warning, correct only for a model meant to be single-arm and deterministic.python -m jinko.cli.validate_model_readiness --model-sid cm-...runs these three checks by default. -
Attach a traceability link to every value-bearing input tagged
s::knowledge. Prefer, in this order: the Extract that holds the value, the Reference that holds the Extract, then any other project item that produced the value. Use an external DOI or URL only when the project holds no such item, and report every external link for review. Use thejinko-referenceskill to upload a missing source PDF as a Reference and to create its Extracts before you link. Put them in the folder that the project's folder convention gives for References. -
Optionally attach scientific scoped tags for model navigation and visualization:
granularity::*for biological or spatial scale; tag color#0cd95e.phenomenon::*for the represented physical or biological process; tag color#f87171.module::*for an implemented mechanism or submodel; tag color#66c09c.readout::*for observation level; tag color#da1d1d.
Use confirmed component definitions and source evidence. Preserve existing tags; leave unsupported classifications unassigned. These custom tags are not readiness requirements. Read scientific scoped tags for selection rules and the QSP, PBPK, and PK/PD example catalog. Pass the family color to
model.create_tag(..., color=...); usetag.set_color(...)when aligning an existing declaration. Tag-family colors are separate from graph component-type colors. -
Use high-level SDK methods and
model.components.batch(version="...")for related component changes. When the model is generated from code or a specification, keep a declarative target and apply it withscripts/sync_model_to_target.py: it diffs the target against the latest model version and commits only real 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 representativeoutputcomponents. For events, verify the expected pre-/post-event change.
To read a method signature, call help() on the object the client returns, for example help(type(model)) or help(model.simple_solve). The SDK has no jinko.model module.
Use scripts/create_minimal_model.py, scripts/sync_model_to_target.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.mdfor component batching, tags, events, formulas, and algebraic rules. Its "Keep piecewise outputs continuous" section applies to every?:formula on an output, such as a log with a floor. - Read
references/unit_docs.mdfor unit semantics and conversion behavior. - Read
references/unit-pitfalls.mdfor errors that pass creation and fail in diagnostics or results, with fixes. - Use
scripts/sync_model_to_target.py --model-sid cm-... --target target.jsonto plan (dry run) and then--apply --base-snapshot <id>to sync an existing model to a JSON target. Its docstring gives the target format. - Read
references/model-validation.mdfor diagnostics and readiness checks. - Read
references/model-combination.mdbeforecombine_with, and to read or resolvemodel.conflicts. - Read
references/scientific-scoped-tags.mdwhen selecting optional scale, phenomenon, module, or readout tags. It includes a broad, extensible catalog of QSP, PBPK, and PK/PD examples.
Slow solves and solver failures
For a timeout, non-finite result, or simple_solve taking at least 15 seconds,
use jinko-task-debug-solving-errors. The threshold is a triage signal; client
wall time includes overhead. Start with python -m jinko.cli.debug_solving --model-sid cm-... --out <new-directory> to retain a pinned diagnostic bundle.
The command does not rerun the model unless --run-simple-solve is supplied.
Keep available __jinko* outputs for performance diagnosis, separate from
scientific comparisons. Do not change solver settings automatically.
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/novainsilico/jinko-skills/jinko-model">View jinko-model on skillZs</a>