Summary

nf-jev exposes TypeSafe System One judgments as ordinary Nextflow functions. A pipeline builds typed questions as values, asks them, and gates on the returned probabilities with plain Nextflow operators.

Jev is not a language model. It generates no text, holds no conversation and calls no tools: it answers typed questions about the state you give it, and returns a probability distribution over the answers you allowed. That makes it something a pipeline can branch on — unlike a number a language model reports about its own confidence, which it invented.

Four functions are provided:

• noul (instructions [, criteria]) — is this true? → probability
• choice (instructions, criteria) — which one? → winner + distribution
• score (instructions, levels) — how much? → position + distribution
• jev (state, questions) — answer them all against one state, in one request

Get Started

Enable the plugin in your pipeline nextflow.config:

plugins {
    id 'nf-jev@0.2.0'
}

Set your credential — either jev.apiKey in the configuration, or the TYPESAFE_API_KEY environment variable:

export TYPESAFE_API_KEY="..."

Then ask a question:

include { jev; noul } from 'plugin/nf-jev'

workflow {
    channel.of('The assembly meets the stated QC bar.')
        .map { text -> jev(text, [clinical: noul('The text gives clinical guidance.')]) }
        .view { answers -> "clinical: ${answers.clinical.noul}" }
}

Configuration

jev {
    provider = 'typesafe'                                // or 'openrouter', see below
    apiKey   = secrets.TYPESAFE_API_KEY                  // or $TYPESAFE_API_KEY
    model    = 'jev-latest'                              // pin a snapshot to fix a result
    endpoint = 'https://api.typesafe.ai/v1/systemone'
    timeout  = 30                                        // seconds, per request
    cacheDir = "$projectDir/.jev-cache"                  // unset = no caching
}

Everything but the key has a default. provider picks the defaults for endpoint and model and names the environment variable the key falls back to; it is inferred from the host of endpoint when left out, so an openrouter.ai endpoint alone is enough to select OpenRouter.

OpenRouter

Jev is also served by the OpenRouter Decisions API. Select it with one setting:

jev {
    provider = 'openrouter'                              // endpoint https://openrouter.ai/api/alpha/decisions
    apiKey   = env('OPENROUTER_API_KEY')                 // the default fallback; or secrets.OPENROUTER_API_KEY
    model    = 'typesafe/jev-1.13'                       // the default; OpenRouter ids are namespaced
}

Only OPENROUTER_API_KEY is read for OpenRouter and only TYPESAFE_API_KEY for TypeSafe. A noul can spell out what a yes and a no mean with the two-argument form, on either provider:

noul('Has this run been seen before?',
     [true: 'The title or accession mentions a prior submission', false: 'Nothing points to one'])

Caching

Set jev.cacheDir and responses are cached, keyed on a SHA-256 of the exact request — model, state and questions. Unset it and nothing is cached. Entries are published atomically, so concurrent runs can share a directory; an entry that will not parse is treated as a miss and the question re-asked, so a truncated file can never poison a pipeline. There is no eviction: rm -rf the directory.

Pin the model with model = 'jev-1.13.0' on TypeSafe or a dated id such as model = 'typesafe/jev-1.13-20260917' on OpenRouter to ensure reproducible caching behavior.

Reading an answer

answers.is_human   // [type: 'noul', noul: 0.98]
answers.assay      // [type: 'choice', choice: 'RNA-seq', confidence: 0.99, probabilities: [...]]
answers.tissue     // [type: 'score', score: 1.97, confidence: 0.96, legend: [...], probabilities: [...]]

Examples

Three runnable pipelines are provided under examples/, each against the live API.

label-samples — fetch ENA run metadata with an ordinary process, label each run against a controlled vocabulary, and split the cohort on a calibrated confidence:

nextflow run examples/label-samples

Output example:

ACCEPT SRR891268   Homo sapiens / ATAC-seq   (p=1.0, cell line p=0.95)
ACCEPT SRR031708   Drosophila melanogaster / RNA-seq   (p=1.0, cell line p=0.73)

route — pick a QC depth per sample and dispatch to different processes. No agent and no generated text; a low-confidence pick falls through to the more thorough branch.

guardrail — screen generated text with a hazard rubric (three nouls and a severity score) in a single request, with the block/review/pass thresholds in nextflow.config:

REVIEW R1  clinical=0.01 overclaim=0.48 identifying=0.04 severity=1.37
BLOCK  R2  clinical=0.96 overclaim=0.78 identifying=0.08 severity=2.95
BLOCK  R3  clinical=0.12 overclaim=0.74 identifying=0.67 severity=2.40

License

Apache License 2.0. See the COPYING file for details.