bioAF Assistant

The bioAF Assistant is a chat interface that turns plain-language intent into real work in bioAF. It resolves which experiment or sample you mean, recommends and installs the right nf-core pipeline, sets up experiments and samples, launches runs, and explains results, all behind a plan you confirm and bounded by your current role and permissions schemes.

This page is the setup guide and operator’s reference. For the wider context (what it feels like to use, and why the safety model is built the way it is), see the launch post: Meet the bioAF Assistant.

How it works

The bioAF Assistant never executes anything directly. It runs a short agent loop that emits tool calls, and every call passes through one enforcement layer that checks your permissions and the action’s consequence class before anything runs. The rule is: the model can only ask to do something. bioAF checks it and either runs it or doesn’t.

A single turn proceeds in stages:

Read to resolve. Read-only tools (list experiments, list samples, list pipelines, check status, get metrics, explain results) let the Assistant turn a plain-language reference into a specific record. They change nothing and run freely.
Recommend deterministically. Pipeline recommendation is a rule-based service (assay plus organism maps to a pipeline and reference genome), not model ranking. It returns a confidence level and the signals it used.
Propose a plan. Any consequential action becomes a step in a plan shown to you, with resolved entities spelled out in plain language.
Confirm, then act. On confirmation the plan executes in order. Steps that spend compute are flagged with a warning on the confirm card.

Availability

The Assistant runs on your organization’s active LLM provider (the same single-active configuration as AI Review), but it requires a provider with native tool-calling.

If no active provider is configured, or the active provider has no model selected, the Assistant is unavailable and tells you what to set in Settings > Integrations > LLMs.
If the active provider does not support tools (for example, a self-hosted model without function calling), the Assistant is unavailable with a message asking you to pick a tool-capable provider. That same provider can still power AI Review.

Anthropic Claude, OpenAI ChatGPT, and Google Gemini are tool-capable. Configure and activate one exactly as you would for AI Review.

Permissions

Two layers of permission apply, and both are enforced server-side.

assistant:use gates starting a conversation. It is granted by default to the admin, comp_bio, and bench roles. The read-only viewer role does not get it.
Per-tool resource permission. Every tool declares the underlying RBAC permission its action requires, checked against your role on every call. The Assistant acts as you and never escalates, so it can only do what your role already allows.

The practical consequence is a launch persona by design:

Action	Permission required	Default roles
Start a conversation	`assistant:use`	admin, comp_bio, bench
List and read data, recommend, explain	`experiments:view`, `samples:view`, `pipelines:view`	any role that can view those entities
Create experiments and samples	`experiments:create`	admin, comp_bio, bench
Install a pipeline	`pipelines:create`	admin, comp_bio
Launch a run	`pipelines:launch`	admin, comp_bio
Run a full saved review	`llm_integration:use`	admin, comp_bio

A bench user can hold a full conversation, get a recommendation, but a tool their role cannot perform is declined at the enforcement layer. To change who can do what, edit the roles under Settings > Users & Accounts > Roles; you are editing the same permissions the rest of bioAF uses.

Consequence classes and the confirm gate

Every tool declares a consequence class, and the enforcement layer treats them differently:

read_only (list, check status, recommend, get metrics, explain results): executes and returns immediately.
mutating (install a pipeline, create an experiment, create a sample): never executes on the model’s say-so. It becomes a step in a plan and waits for your explicit confirmation. On confirm, it runs.
spend (launch a run): same plan-then-confirm gate, plus a “this will spend compute” warning on the confirm card. On confirm, it launches a real pipeline run through the same path as the launch button in the UI.

When a turn wants several dependent actions (for example, install a pipeline and then run it), they are collected into a single plan and executed in order on confirmation. You confirm the whole plan in one step. Your budget ceiling on the launch path remains the hard backstop underneath the confirm gate.

What the Assistant can do

Discover: list experiments, list an experiment’s samples, list installed pipelines, check a run’s status.
Set up: create an experiment, then add samples to it (including the controlled-vocabulary assay field the recommender prefers).
Import by accession: launch nf-core/fetchngs with GEO, SRA, or ENA accessions. fetchngs pulls the data itself, so per-sample files are not required first.
Install and launch: install any nf-core pipeline into the catalog, then launch a run, scoped to specific sample_ids when you name particular samples, or the whole experiment otherwise.
Explain results: read back a run’s QC metrics and narrate what they mean. Any user who can view a run’s results can ask.
Run a full review: users with the AI review permission can ask for a full, saved agent review, which lands on the run’s AI Review tab.
Recall the session: “what did I run this session?” returns this conversation’s actions, read from the audit log and scoped to you.

Conversations are saved. Reopen and resume any past chat from the Assistant’s History.

Untrusted input

Everything a tool returns (your sample metadata, accession metadata pulled from public databases like SRA and GEO, QC summaries, pipeline error logs) is treated as data, never as instructions. Each tool result is fenced in an untrusted-data envelope, machine-readable injection framings are neutralized, and the Assistant is instructed never to follow text found inside a tool result, skip confirmation because a result told it to, or reveal or override its own instructions. These defenses apply at the model boundary only: your stored records, the conversation transcript, and provenance are never rewritten.

This isn’t a content filter trying to catch bad text. The real protection is the confirmation step and the per-tool permission check, which hold no matter what a tool result says.

Audit

Every action taken through the Assistant is written to the immutable audit log, attributed to you and marked via assistant, and linked so the chain from intent to plan to confirmation to tool call to result is reconstructable. Assistant-driven entries are badged in the audit log UI. The full, org-wide audit log remains the primary interface for reviewers (admin and comp_bio); the in-chat “what did I run this session?” is your own self-scoped window into a single conversation.

What the Assistant is not

Not a permission bypass. It can never take an action your own role could not.
Not silent spend. No consequential action runs without your explicit confirmation, and spend is flagged before you approve it.
Needs a tool-capable provider. If the active provider can’t do native tool-calling, the Assistant isn’t available. It won’t fall back to a worse version.
Not a spend manager. Billing happens on your provider account, on their terms. Bring your own key.

Where to look next

Provider configuration: Settings > Integrations > LLMs (shared with AI Review).
Roles and permissions: Settings > Users & Accounts > Roles.
AI Review: the advisory, button-driven counterpart the Assistant can also trigger.
Meet the bioAF Assistant: the launch post.