s2f-agent

s2f-agent is a skill-routing agent for computational genomics. It turns open-ended research questions into deterministic, runnable analysis plans across 11 model families — covering variant-effect prediction, sequence embedding, track prediction, fine-tuning, and environment setup.

Start Here

Fresh-machine bootstrap (recommended):

./scripts/bootstrap.sh
# or
make bootstrap

One-time persistent setup (keeps envs and model caches across sessions):

./scripts/bootstrap.sh \
  --persistent-root "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent" \
  --prefetch-models

# load the generated runtime env in new shells
source "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent/env.sh"

Equivalent Make target:

make bootstrap-persistent PREFETCH_MODELS=1

First run after bootstrap:

./scripts/link_skills.sh
./scripts/route_query.sh --query "Use \$dnabert2 to validate my train/dev/test CSV files"
./scripts/run_agent.sh --query "Need variant-effect guidance for chr12 REF/ALT"
./scripts/smoke_test.sh --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills"

Functional Capabilities

Capability	What it enables	Entry points
Skill-grounded execution	Domain-specific guidance for genomics model families and workflows	`skills//SKILL.md`, `skills-dev//SKILL.md`, `docs/skills-reference.md`
Deterministic routing	Ranked skill selection with `route` / `clarify` decision and confidence	`scripts/route_query.sh`, `registry/routing.yaml`, `docs/routing.md`
Canonical input schema	Shared canonical input keys, aliases, and coordinate conventions	`registry/input_schema.yaml`, `scripts/validate_input_contracts.sh`, `docs/input-schema.md`
Task-contract checks	Detects missing required inputs before execution guidance	`scripts/run_agent.sh`, `registry/task_contracts.yaml`, `docs/contracts.md`
Plan standardization	Emits normalized task plans with runnable steps and expected outputs	`scripts/run_agent.sh`, `registry/output_contracts.yaml`, `registry/recovery_policies.yaml`, `docs/contracts.md`
Plan execution	Dry-run or execute generated steps and verify expected outputs	`scripts/execute_plan.sh`, `docs/scripts-reference.md`
Cross-skill playbook mapping	Maps user intent to reusable task playbooks	`playbooks/*/README.md`, `docs/architecture.md`
Reproducible environment setup	Standardized stack provisioning and one-step bootstrap	`scripts/provision_stack.sh`, `scripts/bootstrap.sh`, `Makefile`, `docs/scripts-reference.md`
Validation and regression checks	Registry, metadata, migration, and routing consistency checks	`scripts/validate_*.sh`, `make validate-agent`, `docs/evals.md`

Application Scenarios

Scenario	Typical objective	Primary skills	Playbook	Docs
Variant-effect analysis	Compare REF vs ALT impact or prioritize variants	`alphagenome-api`, `borzoi-workflows`, `gpn-models`, `evo2-inference`	`variant-effect`	`contracts`, `input-schema`
Embedding and representation	Produce sequence embeddings for downstream analyses	`dnabert2`, `nucleotide-transformer-v3`, `nucleotide-transformer`, `evo2-inference`	`embedding`	`contracts`, `input-schema`
Track prediction workflows	Run sequence-to-signal prediction with model-appropriate constraints	`alphagenome-api`, `nucleotide-transformer-v3`, `borzoi-workflows`, `segment-nt`	`track-prediction`	`contracts`, `input-schema`
Fine-tuning and training setup	Prepare schemas, training configs, and model-specific run paths	`dnabert2`, `nucleotide-transformer-v3`, `bpnet`, `basset-workflows`	`fine-tuning`	`contracts`, `input-schema`
Environment bring-up and migration	Build reproducible stacks and verify operational readiness	`skill-factory` plus stack-specific skills	`environment-setup`	`scripts-reference`, `architecture`

Skill Catalog

The repository currently includes 11 packaged skills.

Status definition:

Stable: canonical package in skills/<skill-id>/
Dev: in-progress package in skills-dev/<skill-id>/
default routing/install/validation only include enabled=true skills in registry/skills.yaml (use --include-disabled to opt in)

Skill ID	Status	Path	Best for	Explicit invocation	Docs
`alphagenome-api`	Stable	`skills/alphagenome-api`	AlphaGenome setup, variant-effect, interval/track prediction, plotting, troubleshooting	`$alphagenome-api`	`SKILL.md` · `references/`
`basset-workflows`	Dev	`skills-dev/basset-workflows`	Legacy Basset Torch7 preprocessing, prediction, interpretation, SAD	`$basset-workflows`	`SKILL.md` · `references/`
`bpnet`	Dev	`skills-dev/bpnet`	BPNet preprocessing, train/predict/SHAP, motif integration	`$bpnet`	`SKILL.md` · `references/`
`borzoi-workflows`	Stable	`skills/borzoi-workflows`	Borzoi setup, tutorials, variant scoring, interpretation	`$borzoi-workflows`	`SKILL.md` · `references/`
`dnabert2`	Stable	`skills/dnabert2`	Embeddings, GUE evaluation, CSV validation, fine-tuning	`$dnabert2`	`SKILL.md` · `references/`
`evo2-inference`	Stable	`skills/evo2-inference`	Evo 2 setup, checkpoint choice, inference, deployment	`$evo2-inference`	`SKILL.md` · `references/`
`gpn-models`	Stable	`skills/gpn-models`	GPN-family framework selection and usage	`$gpn-models`	`SKILL.md` · `references/`
`nucleotide-transformer`	Dev	`skills-dev/nucleotide-transformer`	Classic NT v1/v2 JAX inference, tokenization, embeddings	`$nucleotide-transformer`	`SKILL.md` · `references/`
`nucleotide-transformer-v3`	Stable	`skills/nucleotide-transformer-v3`	NTv3 inference, species conditioning, mode-aware fine-tuning (`prep`/`train`)	`$nucleotide-transformer-v3`	`SKILL.md` · `references/`
`segment-nt`	Stable	`skills/segment-nt`	SegmentNT-family segmentation inference and scaling logic	`$segment-nt`	`SKILL.md` · `references/`
`skill-factory`	Stable	`skills/skill-factory`	Scaffold and validate consistent skill packages from specs	`$skill-factory`	`SKILL.md` · `references/`

Reference notes used during skill development are in Readme/.

Repository Structure

s2f-agent/
├── agent/                  # orchestrator identity, routing and safety policy
├── registry/               # skills index, tags, routing/task/output/recovery contracts
├── skills/                 # canonical stable skill packages
├── skills-dev/             # in-progress skill packages
├── playbooks/              # task-level runbooks plus step-by-step learning guides
├── evals/                  # routing + groundedness + task-success evaluation cases
├── docs/                   # architecture and design notes
├── scripts/                # setup, routing, orchestration, validation tooling
├── Readme/                 # source notes and upstream references
└── README.md

Architecture details: docs/architecture.md.

Routing and Agent Runtime

The s2f agent turns open-ended genomics requests into deterministic, inspectable execution plans.

What it does on each query:

infer (or accept) task intent
rank skill candidates and emit route or clarify
validate required task inputs
generate a normalized plan contract
support dry-run or execution of plan steps

Route vs Run vs Execute

Command	Use when	Primary output
`scripts/route_query.sh`	You only need routing confidence and skill ranking	`decision`, `confidence`, primary/secondary skills
`scripts/run_agent.sh`	You need full orchestration (routing + input checks + plan)	structured agent response with `plan`
`scripts/execute_plan.sh`	You want to dry-run or run generated `plan.runnable_steps`	execution summary + expected output verification

If You Only Run 3 Commands

./scripts/route_query.sh --query "Need variant-effect guidance for hg38 chr12 REF ALT" --format json
./scripts/run_agent.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G' --format json
./scripts/execute_plan.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G'

Note: use single quotes around queries containing $skill to avoid shell expansion.

Happy-Path Example (Variant-Effect)

Route the request:

./scripts/route_query.sh --query "Need variant-effect guidance around chr12 with REF/ALT." --format text

Expected checkpoint: decision=route or decision=clarify with a focused clarify question.

Build a full plan:

./scripts/run_agent.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G' --format json

Expected checkpoint: primary_skill=alphagenome-api, missing_inputs=[], non-null plan.

Validate plan execution path (dry-run):

./scripts/execute_plan.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G' --format text

Expected checkpoint: dry_run=1, failed=0, verify_failed=0.

Agent Output Fields

Field	Meaning	Why it matters
`decision`	`route` or `clarify`	tells you whether execution can proceed immediately
`primary_skill`	selected lead skill	confirms routing target
`missing_inputs`	required inputs not found in query	drives clarify questions and assumption risk
`plan`	normalized execution contract	source of runnable steps and expected outputs
`clarify_question`	focused follow-up question	shortest path to unblock low-confidence routing

Link Map (Contracts vs Learning)

Contract-first references:

Learning in playbooks:

Open the local interactive console:

./scripts/agent_console.sh

Installation and Deployment

This repository can be used in two layers:

Codex skills only: install the packaged skill folders so Codex can route to them immediately.
Full s2f runtime: also provision Python environments and model stacks for local execution.

For extended Codex/plugin notes, see docs/codex-install.md.

Prerequisites

Bash and Git.
Node.js/npm only if installing with npx skills.
Python 3.10+ for local runtime provisioning.
Conda only for the evo2-full path.
NVIDIA GPU + CUDA only for local Evo 2 GPU paths (evo2-light / evo2-full).

1. Recommended: install with `npx skills`

List the skills published by this repository:

npx --yes skills add JiaqiLiZju/s2f-agent --list -a codex --full-depth

Install the stable Codex skill set:

npx --yes skills add JiaqiLiZju/s2f-agent \
  -a codex -g -y --copy --full-depth \
  --skill alphagenome-api \
  --skill borzoi-workflows \
  --skill dnabert2 \
  --skill evo2-inference \
  --skill gpn-models \
  --skill nucleotide-transformer-v3 \
  --skill segment-nt \
  --skill skill-factory

Restart Codex after installing or updating skills.

2. Local checkout install

Use this path when you have cloned the repo and want deterministic local installation without npx.

The default Codex skills directory is:

${CODEX_HOME:-$HOME/.codex}/skills

Copy all enabled, registry-listed skills:

./scripts/link_skills.sh --copy
# or
make link-skills COPY_SKILLS=1

For development, symlink instead of copying so edits are picked up after restarting Codex:

./scripts/link_skills.sh --force

Useful variants:

./scripts/link_skills.sh --list
./scripts/link_skills.sh --skills-dir "$HOME/.codex/skills" --copy --force
./scripts/link_skills.sh --copy alphagenome-api borzoi-workflows dnabert2
./scripts/link_skills.sh --include-disabled

3. Provision software stacks

Installing skills gives Codex the workflow knowledge. Provisioning installs optional runnable model stacks for local execution.

One-step default install: skills + alphagenome + gpn + nt-jax + smoke test.

./scripts/bootstrap.sh
# or
make bootstrap

Provision individual stacks:

./scripts/provision_stack.sh alphagenome
./scripts/provision_stack.sh gpn
./scripts/provision_stack.sh nt-jax
./scripts/provision_stack.sh ntv3-hf
./scripts/provision_stack.sh borzoi

One-time persistent install (keeps deploy envs and caches in a stable location):

./scripts/bootstrap.sh \
  --persistent-root "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent" \
  --prefetch-models

After first setup, load the generated env in new shells:

source "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent/env.sh"

Optional one-step variants:

./scripts/bootstrap.sh --with-ntv3-hf
./scripts/bootstrap.sh --with-borzoi
./scripts/bootstrap.sh --with-evo2-light
./scripts/bootstrap.sh --with-evo2-full

Equivalent Make targets:

make bootstrap-ntv3-hf
make bootstrap-borzoi
make bootstrap-evo2-light
make bootstrap-evo2-full
make bootstrap-persistent

Prefetch model parameters separately (if environments are already prepared):

make prefetch-models
# or
./scripts/prefetch_models.sh --deploy-root "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent/deploy"

One-click cleanup for configured environments and temporary files:

make clean-runtime
# or
./scripts/clean_runtime.sh --yes

Use dry-run first if you want to preview deletions:

./scripts/clean_runtime.sh --dry-run

3. Optional Evo 2 paths

Evo 2 light (requires hardware-specific torch install command before flash-attn):

export TORCH_INSTALL_CMD='$VENV_PYTHON -m pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu128'
./scripts/provision_stack.sh evo2-light

Evo 2 full (active conda environment):

conda create -n evo2-full python=3.11 -y
conda activate evo2-full
./scripts/provision_stack.sh evo2-full

Hosted Evo 2 API path (recommended on macOS or without NVIDIA GPU):

export NVCF_RUN_KEY='your_run_key'
python skills/evo2-inference/scripts/run_hosted_api.py --num-tokens 8 --top-k 1

Full hosted workflow with output plots:

export NVCF_RUN_KEY='your_run_key'
python skills/evo2-inference/scripts/run_real_evo2_workflow.py --output-dir skills/evo2-inference/results

4. Optional hardware-specific JAX override

export JAX_INSTALL_CMD='$VENV_PYTHON -m pip install jax[cuda12]'
./scripts/provision_stack.sh nt-jax

Validation and Troubleshooting

Baseline smoke checks:

./scripts/smoke_test.sh --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills"

Registry and metadata checks:

./scripts/validate_codex_package.sh
./scripts/validate_registry.sh
./scripts/validate_registry_tracking.sh
./scripts/validate_skill_metadata.sh
./scripts/validate_migration_paths.sh

Routing checks and full validation bundle:

./scripts/validate_routing.sh
./scripts/validate_groundedness.sh
./scripts/validate_task_success.sh
make validate-agent

Optional Make shortcuts:

make validate-registry
make validate-registry-tracking
make validate-skill-metadata
make validate-migration-paths
make eval-routing
make eval-groundedness
make eval-task-success
make eval-benchmark
make test-eval-benchmark-mock
make smoke-lite
make route-query QUERY='Need variant-effect guidance' TASK='variant-effect'
make run-agent QUERY='Help me run AlphaGenome predict_variant with RNA output'
make execute-plan QUERY='Need track-prediction plan for human hg38 interval' TASK='track-prediction'

Comparative benchmark notes:

make eval-benchmark runs s2f-agent,gpt-4o,o3-mini by default and requires OPENAI_API_KEY.
Local-only benchmark smoke check: python3 benchmark/tools/eval_benchmark.py --participants s2f-agent --dry-run.
Benchmark section root: benchmark/ (tools/config/prompts/fixtures/runs/reports are centrally managed here).

CI workflow entry:

.github/workflows/agent-ci.yml

Extended smoke test with explicit environment imports:

./scripts/smoke_test.sh \
  --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills" \
  --alphagenome-python /path/to/alphagenome/bin/python \
  --gpn-python /path/to/gpn/bin/python \
  --nt-python /path/to/nt-jax/bin/python \
  --ntv3-python /path/to/ntv3-hf/bin/python \
  --borzoi-python /path/to/borzoi/bin/python \
  --evo2-python /path/to/evo2-light/bin/python

When a workflow fails, start from the skill's references/ folder and then check routing/task configuration under registry/.

Contributing

See CONTRIBUTING.md for how to add skills, run validation, and submit pull requests.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

s2f-agent

Start Here

Table of Contents

Functional Capabilities

Application Scenarios

Skill Catalog

Repository Structure

Routing and Agent Runtime

Route vs Run vs Execute

If You Only Run 3 Commands

Happy-Path Example (Variant-Effect)

Agent Output Fields

Link Map (Contracts vs Learning)

Installation and Deployment

Prerequisites

1. Recommended: install with `npx skills`

2. Local checkout install

3. Provision software stacks

3. Optional Evo 2 paths

4. Optional hardware-specific JAX override

Validation and Troubleshooting

Contributing

Star History

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 57 Commits
.codex-plugin		.codex-plugin
.github/workflows		.github/workflows
agent		agent
benchmark		benchmark
docs		docs
evals		evals
figures		figures
playbooks		playbooks
registry		registry
scripts		scripts
skills		skills
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Makefile		Makefile
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

s2f-agent

Start Here

Table of Contents

Functional Capabilities

Application Scenarios

Skill Catalog

Repository Structure

Routing and Agent Runtime

Route vs Run vs Execute

If You Only Run 3 Commands

Happy-Path Example (Variant-Effect)

Agent Output Fields

Link Map (Contracts vs Learning)

Installation and Deployment

Prerequisites

1. Recommended: install with npx skills

2. Local checkout install

3. Provision software stacks

3. Optional Evo 2 paths

4. Optional hardware-specific JAX override

Validation and Troubleshooting

Contributing

Star History

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

1. Recommended: install with `npx skills`

Packages