Configuration Reference¶
Top-level fields¶
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
version |
integer | ✅ | — | Must be 1 |
repository |
object | ❌ | — | Languages, organisms, analysis types |
files |
object | ❌ | {} |
Metadata, FASTA, FASTQ file definitions |
lineage |
array | ❌ | [] |
Data-to-claim lineage definitions |
reproducibility |
object | ❌ | see defaults | Scoring weights and requirements |
claims |
array | ❌ | [] |
Numerical claim definitions |
figures |
array | ❌ | [] |
Figure provenance definitions |
labels |
object | ❌ | see defaults | Label creation and colours |
comment |
object | ❌ | see defaults | PR comment behaviour |
ai |
object | ❌ | see defaults | AI provider configuration |
Metadata file¶
files:
metadata:
- path: data/sample_metadata.csv
delimiter: auto # auto | "," | "\t" | ";"
id_column: sample_id
required_columns: [sample_id, condition, biological_replicate]
non_null: [sample_id, condition]
unique: [sample_id]
allowed_values:
condition: [control, treatment]
minimum_group_size:
group_by: condition
value: 3
severity: warning # info | warning | error
FASTA file¶
files:
fasta:
- glob: "references/**/*.fa"
alphabet: dna # dna | rna | protein | unrestricted
unique_ids: true
reject_empty_sequences: true
minimum_length: 50
maximum_length: 1000000
FASTQ file¶
files:
fastq:
- glob: "data/**/*.fq"
alphabet: dna
unique_ids: false
reject_empty_sequences: true
maximum_records: 100000
Lineage¶
lineage:
- id: differential-expression
inputs: [data/counts.csv, data/sample_metadata.csv]
code: [analysis/differential_expression.R]
outputs: [results/de_results.csv, figures/figure_2.png]
environment: [renv.lock]
claims: [manuscript/results.md]
stale_output_severity: error
untraceable_output_severity: warning
Lineage rules¶
| Condition | Finding | Language |
|---|---|---|
| Input changed + output unchanged | Possible stale output | "may be stale" |
| Code changed + output unchanged | Possible stale output | "may be stale" |
| Output changed + code/input unchanged | Provenance unclear | "provenance is not demonstrated" |
| Claim changed + evidence unchanged | Claim requires verification | "requires verification" |
| Environment changed + output unchanged | Reproduction recommended | "reproduction recommended" |
| Result changed + manuscript unchanged | Written claim may be stale | "may be stale" |
Claims¶
claims:
- id: il6-treatment-effect
source:
path: manuscript/results.md
marker: BIOTRACE:il6-treatment-effect
evidence:
path: results/de_results.csv
match:
gene: IL6
assertions:
- field: log2FoldChange
operator: ">="
value: 1.7
- field: padj
operator: "<"
value: 0.01
Supported operators: ==, !=, >, >=, <, <=, in, not_in, matches
Figure provenance¶
figures:
- path: figures/figure_2.png
generated_by: [analysis/figure_2.R]
depends_on: [results/de_results.csv]
caption:
path: manuscript/figures.md
marker: figure-2
require_provenance_sidecar: true
Sidecar file figures/figure_2.png.biotrace.json:
{
"schema_version": "1.0",
"figure": "figures/figure_2.png",
"generated_at": "2026-01-15T10:30:00Z",
"command": "Rscript analysis/figure_2.R",
"inputs": {
"results/de_results.csv": "sha256:abc123..."
},
"environment": {
"renv.lock": "sha256:def456..."
}
}
Reproducibility¶
reproducibility:
require_environment: true
require_lockfile: true
entrypoints: ["Rscript analysis/differential_expression.R"]
seed_patterns: ["set.seed(", "random_state=", "numpy.random.seed("]
require_session_info: false
weights:
environment_definition: 15
dependency_lock: 15
dependency_constraints: 10
random_seed: 10
documented_entrypoint: 15
output_manifest: 15
figure_provenance: 10
data_checksums: 5
session_information: 5
Reproducibility score formula¶
score = (sum of passed component weights) / (sum of applicable component weights) × 100
Components marked "not applicable" do not reduce the score. The result is an integer from 0 to 100.
| Score range | Label |
|---|---|
| 80–100 | reproducibility:strong |
| 50–79 | reproducibility:partial |
| 0–49 | reproducibility:weak |
AI configuration¶
AI-assisted observations are optional, bring-your-own-key, and advisory only — they never
override deterministic checks or the reproducibility score. provider accepts either a single
provider name or an ordered priority list; if the first provider has no key configured or its
call fails, BioTrace automatically falls through to the next one.
ai:
enabled: auto # auto | "true" | "false"
provider: [openai-compatible, anthropic] # or a single string, e.g. anthropic
model: "" # optional; blank = auto-discovered per provider
base_url: "" # optional override for the primary provider only
tasks: [pr_summary, method_drift, claim_candidates, reviewer_checklist]
fail_open: true
minimum_confidence: 0.7
maximum_changed_files: 100
maximum_patch_bytes: 150000
never_send: ["data/raw/**", "**/*secret*"]
| Field | Type | Default | Description |
|---|---|---|---|
enabled |
string | auto |
auto, "true", or "false" |
provider |
string or array | openai-compatible |
One or more of openai-compatible, anthropic, gemini |
model |
string | "" |
Model for the primary provider; blank = auto-discovered |
base_url |
string | "" |
Base URL override for the primary provider |
tasks |
array | see defaults | Which AI tasks to request |
fail_open |
boolean | true |
Whether an AI failure blocks the run |
minimum_confidence |
number | 0.8 |
Drops observations below this confidence |
maximum_changed_files |
integer | 100 |
Cap on files sent to the AI provider |
maximum_patch_bytes |
integer | 150000 |
Truncates patch content to this size |
never_send |
array | see defaults | Glob patterns always excluded from AI requests |
Model auto-discovery¶
Leaving model blank makes BioTrace fetch the provider's current model list and pick a sensible
default automatically, avoiding a hardcoded model name that the provider later renames or
retires. This applies independently to every provider in the priority list — a model you set
only applies to the primary (first) provider; any fallback provider always auto-discovers its own
model, since a model identifier from one provider is never valid for another.
API keys¶
ai-key-env (an action.yml input, not a config file field) names the environment variable
holding the primary provider's API key, defaulting to BIOTRACE_AI_API_KEY. Providers listed
after the first are looked up via fixed conventional environment variable names instead of
additional inputs:
| Provider | Conventional environment variable |
|---|---|
openai-compatible |
BIOTRACE_OPENAI_API_KEY |
anthropic |
BIOTRACE_ANTHROPIC_API_KEY |
gemini |
BIOTRACE_GEMINI_API_KEY |
Set these in the workflow's env: block, sourced from repository or organization secrets so
GitHub masks them in logs:
- uses: rotsl/biotrace@v1
with:
ai-enabled: auto
ai-provider: openai-compatible,anthropic,gemini
env:
BIOTRACE_AI_API_KEY: ${{ secrets.BIOTRACE_AI_API_KEY }}
BIOTRACE_ANTHROPIC_API_KEY: ${{ secrets.BIOTRACE_ANTHROPIC_API_KEY }}
BIOTRACE_GEMINI_API_KEY: ${{ secrets.BIOTRACE_GEMINI_API_KEY }}
With ai-enabled: auto, AI runs if any provider in the resolved priority list has a usable key
— not only the primary's.