Skip to content
Back to search

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…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jiaqili1024--s2f-agent/badge.svg)](/listings/jiaqili1024--s2f-agent)

HTML

<a href="/listings/jiaqili1024--s2f-agent"><img src="/api/listings/jiaqili1024--s2f-agent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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`](./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 alphagenome-research \
  --skill basenji-workflows \
  --skill bpnet-skill \
  --skill borzoi-workflows \
  --skill caduceus-inference \
  --skill chrombpnet-skill \
  --skill dnabert2 \
  --skill evo2-inference \
  --skill gpn-models \
  --skill hyenadna-inference \
  --skill nucleotide-transformer-v3 \
  --skill pangolin-workflows \
  --skill segment-nt \
  --skill sei-workflows \
  --skill spliceai-workflows \
  --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`):

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 503 lines
  1. # s2f-agent
  2. `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.
  3. [![CI](https://github.com/JiaqiLiZju/s2f-agent/actions/workflows/agent-ci.yml/badge.svg)](https://github.com/JiaqiLiZju/s2f-agent/actions/workflows/agent-ci.yml)
  4. ![Python](https://img.shields.io/badge/python-3.10%2B-blue)
  5. ![Shell](https://img.shields.io/badge/shell-bash-lightgrey)
  6. ## Start Here
  7. Fresh-machine bootstrap (recommended):
  8. ```bash
  9. ./scripts/bootstrap.sh
  10. # or
  11. make bootstrap
  12. ```
  13. One-time persistent setup (keeps envs and model caches across sessions):
  14. ```bash
  15. ./scripts/bootstrap.sh \
  16. --persistent-root "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent" \
  17. --prefetch-models
  18. # load the generated runtime env in new shells
  19. source "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent/env.sh"
  20. ```
  21. Equivalent Make target:
  22. ```bash
  23. make bootstrap-persistent PREFETCH_MODELS=1
  24. ```
  25. First run after bootstrap:
  26. ```bash
  27. ./scripts/link_skills.sh
  28. ./scripts/route_query.sh --query "Use \$dnabert2 to validate my train/dev/test CSV files"
  29. ./scripts/run_agent.sh --query "Need variant-effect guidance for chr12 REF/ALT"
  30. ./scripts/smoke_test.sh --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills"
  31. ```
  32. ## Table of Contents
  33. - [Functional Capabilities](#functional-capabilities)
  34. - [Application Scenarios](#application-scenarios)
  35. - [Skill Catalog](#skill-catalog)
  36. - [Repository Structure](#repository-structure)
  37. - [Routing and Agent Runtime](#routing-and-agent-runtime)
  38. - [Installation and Deployment](#installation-and-deployment)
  39. - [Validation and Troubleshooting](#validation-and-troubleshooting)
  40. - [Contributing](#contributing)
  41. - [Star History](#star-history)
  42. ## Functional Capabilities
  43. | Capability | What it enables | Entry points |
  44. | --- | --- | --- |
  45. | Skill-grounded execution | Domain-specific guidance for genomics model families and workflows | `skills/*/SKILL.md`, `skills-dev/*/SKILL.md`, [`docs/skills-reference.md`](./docs/skills-reference.md) |
  46. | Deterministic routing | Ranked skill selection with `route` / `clarify` decision and confidence | `scripts/route_query.sh`, `registry/routing.yaml`, [`docs/routing.md`](./docs/routing.md) |
  47. | Canonical input schema | Shared canonical input keys, aliases, and coordinate conventions | `registry/input_schema.yaml`, `scripts/validate_input_contracts.sh`, [`docs/input-schema.md`](./docs/input-schema.md) |
  48. | Task-contract checks | Detects missing required inputs before execution guidance | `scripts/run_agent.sh`, `registry/task_contracts.yaml`, [`docs/contracts.md`](./docs/contracts.md) |
  49. | 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`](./docs/contracts.md) |
  50. | Plan execution | Dry-run or execute generated steps and verify expected outputs | `scripts/execute_plan.sh`, [`docs/scripts-reference.md`](./docs/scripts-reference.md) |
  51. | Cross-skill playbook mapping | Maps user intent to reusable task playbooks | `playbooks/*/README.md`, [`docs/architecture.md`](./docs/architecture.md) |
  52. | Reproducible environment setup | Standardized stack provisioning and one-step bootstrap | `scripts/provision_stack.sh`, `scripts/bootstrap.sh`, `Makefile`, [`docs/scripts-reference.md`](./docs/scripts-reference.md) |
  53. | Validation and regression checks | Registry, metadata, migration, and routing consistency checks | `scripts/validate_*.sh`, `make validate-agent`, [`docs/evals.md`](./docs/evals.md) |
  54. ## Application Scenarios
  55. | Scenario | Typical objective | Primary skills | Playbook | Docs |
  56. | --- | --- | --- | --- | --- |
  57. | Variant-effect analysis | Compare REF vs ALT impact or prioritize variants | `alphagenome-api`, `borzoi-workflows`, `gpn-models`, `evo2-inference` | [`variant-effect`](./playbooks/variant-effect/README.md) | [`contracts`](./docs/contracts.md), [`input-schema`](./docs/input-schema.md) |
  58. | Embedding and representation | Produce sequence embeddings for downstream analyses | `dnabert2`, `nucleotide-transformer-v3`, `nucleotide-transformer`, `evo2-inference` | [`embedding`](./playbooks/embedding/README.md) | [`contracts`](./docs/contracts.md), [`input-schema`](./docs/input-schema.md) |
  59. | Track prediction workflows | Run sequence-to-signal prediction with model-appropriate constraints | `alphagenome-api`, `nucleotide-transformer-v3`, `borzoi-workflows`, `segment-nt` | [`track-prediction`](./playbooks/track-prediction/README.md) | [`contracts`](./docs/contracts.md), [`input-schema`](./docs/input-schema.md) |
  60. | Fine-tuning and training setup | Prepare schemas, training configs, and model-specific run paths | `dnabert2`, `nucleotide-transformer-v3`, `bpnet-skill`, `basset-workflows` | [`fine-tuning`](./playbooks/fine-tuning/README.md) | [`contracts`](./docs/contracts.md), [`input-schema`](./docs/input-schema.md) |
  61. | Environment bring-up and migration | Build reproducible stacks and verify operational readiness | `skill-factory` plus stack-specific skills | [`environment-setup`](./playbooks/environment-setup/README.md) | [`scripts-reference`](./docs/scripts-reference.md), [`architecture`](./docs/architecture.md) |
  62. ## Skill Catalog
  63. The repository catalog currently includes **20** packaged skills.
  64. Status definition:
  65. - `Stable`: canonical package in `skills/<skill-id>/`
  66. - `Dev`: in-progress package in `skills-dev/<skill-id>/`
  67. - default routing/install/validation only include `enabled=true` skills in `registry/skills.yaml` (use `--include-disabled` to opt in)
  68. | Skill ID | Status | Path | Best for | Explicit invocation | Docs |
  69. | --- | --- | --- | --- | --- | --- |
  70. | `alphagenome-api` | Stable | `skills/alphagenome-api` | AlphaGenome setup, variant-effect, interval/track prediction, plotting, troubleshooting | `$alphagenome-api` | [`SKILL.md`](./skills/alphagenome-api/SKILL.md) · [`references/`](./skills/alphagenome-api/references/) |
  71. | `alphagenome-research` | Stable | `skills/alphagenome-research` | Local AlphaGenome model setup, sequence/interval prediction, variant scoring | `$alphagenome-research` | [`SKILL.md`](./skills/alphagenome-research/SKILL.md) · [`references/`](./skills/alphagenome-research/references/) |
  72. | `basenji-workflows` | Stable | `skills/basenji-workflows` | Basenji training, binned prediction, SAD/SED, mutagenesis, motif analysis | `$basenji-workflows` | [`SKILL.md`](./skills/basenji-workflows/SKILL.md) · [`references/`](./skills/basenji-workflows/references/) |
  73. | `basset-workflows` | Dev | `skills-dev/basset-workflows` | Legacy Basset Torch7 preprocessing, prediction, interpretation, SAD | `$basset-workflows` | [`SKILL.md`](./skills-dev/basset-workflows/SKILL.md) · [`references/`](./skills-dev/basset-workflows/references/) |
  74. | `bpnet` | Dev | `skills-dev/bpnet` | BPNet preprocessing, train/predict/SHAP, motif integration | `$bpnet` | [`SKILL.md`](./skills-dev/bpnet/SKILL.md) · [`references/`](./skills-dev/bpnet/references/) |
  75. | `bpnet-skill` | Stable | `skills/bpnet-skill` | BPNet 2.x setup, input validation, train/predict/SHAP, motif integration | `$bpnet-skill` | [`SKILL.md`](./skills/bpnet-skill/SKILL.md) · [`references/`](./skills/bpnet-skill/references/) |
  76. | `caduceus-inference` | Stable | `skills/caduceus-inference` | Caduceus masked-LM, RC-aware embeddings, VEP dump, fine-tuning | `$caduceus-inference` | [`SKILL.md`](./skills/caduceus-inference/SKILL.md) · [`references/`](./skills/caduceus-inference/references/) |
  77. | `chrombpnet-skill` | Stable | `skills/chrombpnet-skill` | ChromBPNet bias-factorized ATAC/DNase training and interpretation | `$chrombpnet-skill` | [`SKILL.md`](./skills/chrombpnet-skill/SKILL.md) · [`references/`](./skills/chrombpnet-skill/references/) |
  78. | `borzoi-workflows` | Stable | `skills/borzoi-workflows` | Borzoi setup, tutorials, variant scoring, interpretation | `$borzoi-workflows` | [`SKILL.md`](./skills/borzoi-workflows/SKILL.md) · [`references/`](./skills/borzoi-workflows/references/) |
  79. | `dnabert2` | Stable | `skills/dnabert2` | Embeddings, GUE evaluation, CSV validation, fine-tuning | `$dnabert2` | [`SKILL.md`](./skills/dnabert2/SKILL.md) · [`references/`](./skills/dnabert2/references/) |
  80. | `evo2-inference` | Stable | `skills/evo2-inference` | Evo 2 setup, checkpoint choice, inference, deployment | `$evo2-inference` | [`SKILL.md`](./skills/evo2-inference/SKILL.md) · [`references/`](./skills/evo2-inference/references/) |
  81. | `gpn-models` | Stable | `skills/gpn-models` | GPN-family framework selection and usage | `$gpn-models` | [`SKILL.md`](./skills/gpn-models/SKILL.md) · [`references/`](./skills/gpn-models/references/) |
  82. | `hyenadna-inference` | Stable | `skills/hyenadna-inference` | HyenaDNA long-context embeddings, classification, pretraining and fine-tuning | `$hyenadna-inference` | [`SKILL.md`](./skills/hyenadna-inference/SKILL.md) · [`references/`](./skills/hyenadna-inference/references/) |
  83. | `nucleotide-transformer` | Dev | `skills-dev/nucleotide-transformer` | Classic NT v1/v2 JAX inference, tokenization, embeddings | `$nucleotide-transformer` | [`SKILL.md`](./skills-dev/nucleotide-transformer/SKILL.md) · [`references/`](./skills-dev/nucleotide-transformer/references/) |
  84. | `nucleotide-transformer-v3` | Stable | `skills/nucleotide-transformer-v3` | NTv3 inference, species conditioning, mode-aware fine-tuning (`prep`/`train`) | `$nucleotide-transformer-v3` | [`SKILL.md`](./skills/nucleotide-transformer-v3/SKILL.md) · [`references/`](./skills/nucleotide-transformer-v3/references/) |
  85. | `pangolin-workflows` | Stable | `skills/pangolin-workflows` | Pangolin VCF/CSV splice strength, annotation DB, masking and cutoffs | `$pangolin-workflows` | [`SKILL.md`](./skills/pangolin-workflows/SKILL.md) · [`references/`](./skills/pangolin-workflows/references/) |
  86. | `segment-nt` | Stable | `skills/segment-nt` | SegmentNT-family segmentation inference and scaling logic | `$segment-nt` | [`SKILL.md`](./skills/segment-nt/SKILL.md) · [`references/`](./skills/segment-nt/references/) |
  87. | `sei-workflows` | Stable | `skills/sei-workflows` | Sei chromatin profiles, 40 sequence classes and variant effects | `$sei-workflows` | [`SKILL.md`](./skills/sei-workflows/SKILL.md) · [`references/`](./skills/sei-workflows/references/) |
  88. | `skill-factory` | Stable | `skills/skill-factory` | Scaffold and validate consistent skill packages from specs | `$skill-factory` | [`SKILL.md`](./skills/skill-factory/SKILL.md) · [`references/`](./skills/skill-factory/references/) |
  89. | `spliceai-workflows` | Stable | `skills/spliceai-workflows` | SpliceAI VCF delta-score annotation and custom sequence scoring | `$spliceai-workflows` | [`SKILL.md`](./skills/spliceai-workflows/SKILL.md) · [`references/`](./skills/spliceai-workflows/references/) |
  90. Reference notes used during skill development are in [`Readme/`](./Readme/).
  91. ## Repository Structure
  92. ```text
  93. s2f-agent/
  94. ├── agent/ # orchestrator identity, routing and safety policy
  95. ├── registry/ # skills index, tags, routing/task/output/recovery contracts
  96. ├── skills/ # canonical stable skill packages
  97. ├── skills-dev/ # in-progress skill packages
  98. ├── playbooks/ # task-level runbooks plus step-by-step learning guides
  99. ├── evals/ # routing + groundedness + task-success evaluation cases
  100. ├── docs/ # architecture and design notes
  101. ├── scripts/ # setup, routing, orchestration, validation tooling
  102. ├── Readme/ # source notes and upstream references
  103. └── README.md
  104. ```
  105. Architecture details: [`docs/architecture.md`](./docs/architecture.md).
  106. ## Routing and Agent Runtime
  107. The `s2f` agent turns open-ended genomics requests into deterministic, inspectable execution plans.
  108. What it does on each query:
  109. 1. infer (or accept) task intent
  110. 2. rank skill candidates and emit `route` or `clarify`
  111. 3. validate required task inputs
  112. 4. generate a normalized `plan` contract
  113. 5. support dry-run or execution of plan steps
  114. ### Route vs Run vs Execute
  115. | Command | Use when | Primary output |
  116. | --- | --- | --- |
  117. | `scripts/route_query.sh` | You only need routing confidence and skill ranking | `decision`, `confidence`, primary/secondary skills |
  118. | `scripts/run_agent.sh` | You need full orchestration (routing + input checks + plan) | structured agent response with `plan` |
  119. | `scripts/execute_plan.sh` | You want to dry-run or run generated `plan.runnable_steps` | execution summary + expected output verification |
  120. ### If You Only Run 3 Commands
  121. ```bash
  122. ./scripts/route_query.sh --query "Need variant-effect guidance for hg38 chr12 REF ALT" --format json
  123. ./scripts/run_agent.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G' --format json
  124. ./scripts/execute_plan.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G'
  125. ```
  126. Note: use single quotes around queries containing `$skill` to avoid shell expansion.
  127. ### Happy-Path Example (Variant-Effect)
  128. 1. Route the request:
  129. ```bash
  130. ./scripts/route_query.sh --query "Need variant-effect guidance around chr12 with REF/ALT." --format text
  131. ```
  132. Expected checkpoint: `decision=route` or `decision=clarify` with a focused clarify question.
  133. 2. Build a full plan:
  134. ```bash
  135. ./scripts/run_agent.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G' --format json
  136. ```
  137. Expected checkpoint: `primary_skill=alphagenome-api`, `missing_inputs=[]`, non-null `plan`.
  138. 3. Validate plan execution path (dry-run):
  139. ```bash
  140. ./scripts/execute_plan.sh --task variant-effect --query 'Use $alphagenome-api variant-effect on hg38 chr12 REF A ALT G' --format text
  141. ```
  142. Expected checkpoint: `dry_run=1`, `failed=0`, `verify_failed=0`.
  143. ### Agent Output Fields
  144. | Field | Meaning | Why it matters |
  145. | --- | --- | --- |
  146. | `decision` | `route` or `clarify` | tells you whether execution can proceed immediately |
  147. | `primary_skill` | selected lead skill | confirms routing target |
  148. | `missing_inputs` | required inputs not found in query | drives clarify questions and assumption risk |
  149. | `plan` | normalized execution contract | source of runnable steps and expected outputs |
  150. | `clarify_question` | focused follow-up question | shortest path to unblock low-confidence routing |
  151. ### Link Map (Contracts vs Learning)
  152. Contract-first references:
  153. - [`playbooks/variant-effect/README.md`](./playbooks/variant-effect/README.md)
  154. - [`playbooks/embedding/README.md`](./playbooks/embedding/README.md)
  155. - [`playbooks/track-prediction/README.md`](./playbooks/track-prediction/README.md)
  156. - [`playbooks/fine-tuning/README.md`](./playbooks/fine-tuning/README.md)
  157. - [`playbooks/environment-setup/README.md`](./playbooks/environment-setup/README.md)
  158. - [`registry/input_schema.yaml`](./registry/input_schema.yaml)
  159. Learning in playbooks:
  160. - [`playbooks/README.md`](./playbooks/README.md)
  161. - [`playbooks/getting-started/README.md`](./playbooks/getting-started/README.md)
  162. - [`playbooks/variant-effect/README.md`](./playbooks/variant-effect/README.md)
  163. - [`playbooks/embedding/README.md`](./playbooks/embedding/README.md)
  164. - [`playbooks/track-prediction/README.md`](./playbooks/track-prediction/README.md)
  165. - [`playbooks/fine-tuning/README.md`](./playbooks/fine-tuning/README.md)
  166. - [`playbooks/environment-setup/README.md`](./playbooks/environment-setup/README.md)
  167. - [`playbooks/troubleshooting/README.md`](./playbooks/troubleshooting/README.md)
  168. Open the local interactive console:
  169. ```bash
  170. ./scripts/agent_console.sh
  171. ```
  172. ## Installation and Deployment
  173. This repository can be used in two layers:
  174. - **Codex skills only**: install the packaged skill folders so Codex can route to them immediately.
  175. - **Full s2f runtime**: also provision Python environments and model stacks for local execution.
  176. For extended Codex/plugin notes, see [`docs/codex-install.md`](./docs/codex-install.md).
  177. ### Prerequisites
  178. - Bash and Git.
  179. - Node.js/npm only if installing with `npx skills`.
  180. - Python 3.10+ for local runtime provisioning.
  181. - Conda only for the `evo2-full` path.
  182. - NVIDIA GPU + CUDA only for local Evo 2 GPU paths (`evo2-light` / `evo2-full`).
  183. ### 1. Recommended: install with `npx skills`
  184. List the skills published by this repository:
  185. ```bash
  186. npx --yes skills add JiaqiLiZju/s2f-agent --list -a codex --full-depth
  187. ```
  188. Install the stable Codex skill set:
  189. ```bash
  190. npx --yes skills add JiaqiLiZju/s2f-agent \
  191. -a codex -g -y --copy --full-depth \
  192. --skill alphagenome-api \
  193. --skill alphagenome-research \
  194. --skill basenji-workflows \
  195. --skill bpnet-skill \
  196. --skill borzoi-workflows \
  197. --skill caduceus-inference \
  198. --skill chrombpnet-skill \
  199. --skill dnabert2 \
  200. --skill evo2-inference \
  201. --skill gpn-models \
  202. --skill hyenadna-inference \
  203. --skill nucleotide-transformer-v3 \
  204. --skill pangolin-workflows \
  205. --skill segment-nt \
  206. --skill sei-workflows \
  207. --skill spliceai-workflows \
  208. --skill skill-factory
  209. ```
  210. Restart Codex after installing or updating skills.
  211. ### 2. Local checkout install
  212. Use this path when you have cloned the repo and want deterministic local installation without `npx`.
  213. The default Codex skills directory is:
  214. ```bash
  215. ${CODEX_HOME:-$HOME/.codex}/skills
  216. ```
  217. Copy all enabled, registry-listed skills:
  218. ```bash
  219. ./scripts/link_skills.sh --copy
  220. # or
  221. make link-skills COPY_SKILLS=1
  222. ```
  223. For development, symlink instead of copying so edits are picked up after restarting Codex:
  224. ```bash
  225. ./scripts/link_skills.sh --force
  226. ```
  227. Useful variants:
  228. ```bash
  229. ./scripts/link_skills.sh --list
  230. ./scripts/link_skills.sh --skills-dir "$HOME/.codex/skills" --copy --force
  231. ./scripts/link_skills.sh --copy alphagenome-api borzoi-workflows dnabert2
  232. ./scripts/link_skills.sh --include-disabled
  233. ```
  234. ### 3. Provision software stacks
  235. Installing skills gives Codex the workflow knowledge. Provisioning installs optional runnable model stacks for local execution.
  236. One-step default install: skills + `alphagenome` + `gpn` + `nt-jax` + smoke test.
  237. ```bash
  238. ./scripts/bootstrap.sh
  239. # or
  240. make bootstrap
  241. ```
  242. Provision individual stacks:
  243. ```bash
  244. ./scripts/provision_stack.sh alphagenome
  245. ./scripts/provision_stack.sh gpn
  246. ./scripts/provision_stack.sh nt-jax
  247. ./scripts/provision_stack.sh ntv3-hf
  248. ./scripts/provision_stack.sh borzoi
  249. ```
  250. One-time persistent install (keeps deploy envs and caches in a stable location):
  251. ```bash
  252. ./scripts/bootstrap.sh \
  253. --persistent-root "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent" \
  254. --prefetch-models
  255. ```
  256. After first setup, load the generated env in new shells:
  257. ```bash
  258. source "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent/env.sh"
  259. ```
  260. Optional one-step variants:
  261. ```bash
  262. ./scripts/bootstrap.sh --with-ntv3-hf
  263. ./scripts/bootstrap.sh --with-borzoi
  264. ./scripts/bootstrap.sh --with-evo2-light
  265. ./scripts/bootstrap.sh --with-evo2-full
  266. ```
  267. Equivalent Make targets:
  268. ```bash
  269. make bootstrap-ntv3-hf
  270. make bootstrap-borzoi
  271. make bootstrap-evo2-light
  272. make bootstrap-evo2-full
  273. make bootstrap-persistent
  274. ```
  275. Prefetch model parameters separately (if environments are already prepared):
  276. ```bash
  277. make prefetch-models
  278. # or
  279. ./scripts/prefetch_models.sh --deploy-root "${XDG_CACHE_HOME:-$HOME/.cache}/s2f-agent/deploy"
  280. ```
  281. One-click cleanup for configured environments and temporary files:
  282. ```bash
  283. make clean-runtime
  284. # or
  285. ./scripts/clean_runtime.sh --yes
  286. ```
  287. Use dry-run first if you want to preview deletions:
  288. ```bash
  289. ./scripts/clean_runtime.sh --dry-run
  290. ```
  291. ### 3. Optional Evo 2 paths
  292. Evo 2 light (requires hardware-specific torch install command before `flash-attn`):
  293. ```bash
  294. export TORCH_INSTALL_CMD='$VENV_PYTHON -m pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu128'
  295. ./scripts/provision_stack.sh evo2-light
  296. ```
  297. Evo 2 full (active conda environment):
  298. ```bash
  299. conda create -n evo2-full python=3.11 -y
  300. conda activate evo2-full
  301. ./scripts/provision_stack.sh evo2-full
  302. ```
  303. Hosted Evo 2 API path (recommended on macOS or without NVIDIA GPU):
  304. ```bash
  305. export NVCF_RUN_KEY='your_run_key'
  306. python skills/evo2-inference/scripts/run_hosted_api.py --num-tokens 8 --top-k 1
  307. ```
  308. Full hosted workflow with output plots:
  309. ```bash
  310. export NVCF_RUN_KEY='your_run_key'
  311. python skills/evo2-inference/scripts/run_real_evo2_workflow.py --output-dir skills/evo2-inference/results
  312. ```
  313. ### 4. Optional hardware-specific JAX override
  314. ```bash
  315. export JAX_INSTALL_CMD='$VENV_PYTHON -m pip install jax[cuda12]'
  316. ./scripts/provision_stack.sh nt-jax
  317. ```
  318. ## Validation and Troubleshooting
  319. Baseline smoke checks:
  320. ```bash
  321. ./scripts/smoke_test.sh --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills"
  322. ```
  323. Registry and metadata checks:
  324. ```bash
  325. ./scripts/validate_codex_package.sh
  326. ./scripts/validate_registry.sh
  327. ./scripts/validate_registry_tracking.sh
  328. ./scripts/validate_skill_metadata.sh
  329. ./scripts/validate_migration_paths.sh
  330. ```
  331. Routing checks and full validation bundle:
  332. ```bash
  333. ./scripts/validate_routing.sh
  334. ./scripts/validate_groundedness.sh
  335. ./scripts/validate_task_success.sh
  336. make validate-agent
  337. ```
  338. Optional Make shortcuts:
  339. ```bash
  340. make validate-registry
  341. make validate-registry-tracking
  342. make validate-skill-metadata
  343. make validate-migration-paths
  344. make eval-routing
  345. make eval-groundedness
  346. make eval-task-success
  347. make eval-benchmark
  348. make test-eval-benchmark-mock
  349. make smoke-lite
  350. make route-query QUERY='Need variant-effect guidance' TASK='variant-effect'
  351. make run-agent QUERY='Help me run AlphaGenome predict_variant with RNA output'
  352. make execute-plan QUERY='Need track-prediction plan for human hg38 interval' TASK='track-prediction'
  353. ```
  354. Comparative benchmark notes:
  355. - `make eval-benchmark` runs `s2f-agent,gpt-4o,o3-mini` by default and requires `OPENAI_API_KEY`.
  356. - Local-only benchmark smoke check: `python3 benchmark/tools/eval_benchmark.py --participants s2f-agent --dry-run`.
  357. - Benchmark section root: `benchmark/` (tools/config/prompts/fixtures/runs/reports are centrally managed here).
  358. CI workflow entry:
  359. ```bash
  360. .github/workflows/agent-ci.yml
  361. ```
  362. Extended smoke test with explicit environment imports:
  363. ```bash
  364. ./scripts/smoke_test.sh \
  365. --skills-dir "${CODEX_HOME:-$HOME/.codex}/skills" \
  366. --alphagenome-python /path/to/alphagenome/bin/python \
  367. --gpn-python /path/to/gpn/bin/python \
  368. --nt-python /path/to/nt-jax/bin/python \
  369. --ntv3-python /path/to/ntv3-hf/bin/python \
  370. --borzoi-python /path/to/borzoi/bin/python \
  371. --evo2-python /path/to/evo2-light/bin/python
  372. ```
  373. When a workflow fails, start from the skill's `references/` folder and then check routing/task configuration under `registry/`.
  374. ## Contributing
  375. See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to add skills, run validation, and submit pull requests.
  376. ## License
  377. This repository is licensed under the [Apache License 2.0](./LICENSE). Third-party models, datasets, and dependencies may have their own license terms.
  378. ## Star History
  379. [![Star History Chart](https://api.star-history.com/svg?repos=JiaqiLiZju/s2f-agent&type=Date)](https://star-history.com/#JiaqiLiZju/s2f-agent&Date)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.