Skip to content

AI-Powered CLI#

oxo-flow can use AI (DeepSeek, Claude, OpenAI, or Ollama) to help you create, validate, and fix bioinformatics workflows. AI is optional — no AI code runs unless explicitly enabled.

Design principle: Add one line of config. AI activates automatically on all suitable commands.


Quick Start#

1. Configure Your AI Provider#

oxo-flow supports any AI provider with an OpenAI-compatible or Anthropic-compatible API. Set the provider and your API key via environment variables:

# DeepSeek (OpenAI-compatible)
export OXO_FLOW_AI_PROVIDER=deepseek
export DEEPSEEK_API_KEY="sk-<YOUR-KEY>"

# Claude (Anthropic)
export OXO_FLOW_AI_PROVIDER=claude
export ANTHROPIC_AUTH_TOKEN="sk-ant-<YOUR-KEY>"

# OpenAI
export OXO_FLOW_AI_PROVIDER=openai
export OPENAI_API_KEY="sk-<YOUR-KEY>"

# Any OpenAI-compatible service (Groq, Together, Azure, Fireworks, etc.)
export OXO_FLOW_AI_PROVIDER=openai
export OPENAI_BASE_URL="https://api.groq.com/openai/v1"
export OPENAI_API_KEY="gsk_<YOUR-KEY>"
export OPENAI_MODEL="llama-3.1-70b"

# Any Anthropic-compatible service
export OXO_FLOW_AI_PROVIDER=claude
export ANTHROPIC_BASE_URL="https://your-custom-endpoint"
export ANTHROPIC_AUTH_TOKEN="<YOUR-KEY>"

# Local Ollama (no API key needed)
export OXO_FLOW_AI_PROVIDER=ollama
export OXO_FLOW_AI_API_URL="http://localhost:11434"
export OXO_FLOW_AI_MODEL="llama3"

# Zero-config: if OXO_FLOW_AI_PROVIDER is unset and you already export
# ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL (gateway) or OPENAI_API_KEY
# (openai-compatible), oxo-flow auto-detects the provider — no extra
# variables needed. See "Environment Variables" below for the exact rules.

Configuration persists to ~/.oxo-flow/ai_config.json after first use (or to the file named by OXO_FLOW_AI_CONFIG, when set).

2. Enable AI in Your Workflow#

Add one section to your .oxoflow file:

[ai]
enabled = true

That's it. Now all AI-capable commands auto-activate without extra flags:

oxo-flow dry-run workflow.oxoflow     # AI analysis runs automatically
oxo-flow validate workflow.oxoflow   # AI semantic validation
oxo-flow run workflow.oxoflow        # AI error recovery on failure

3. Generate a New Workflow#

oxo-flow template "RNA-seq analysis with STAR alignment and featureCounts quantification" --ai

4. Override with CLI Flags#

# Force AI on (even without [ai] section)
oxo-flow dry-run workflow.oxoflow --ai

# Force AI off (even with [ai] section)
# (just don't pass --ai — AI is only auto-detected, never forced)

5. Review and Run#

# Review the generated workflow
cat rnaseq_analysis_with.oxoflow

# Validate it
oxo-flow validate rnaseq_analysis_with.oxoflow

# Run it
oxo-flow run rnaseq_analysis_with.oxoflow

Template Command Reference#

Basic Generation#

oxo-flow template "<description>" --ai

Examples:

oxo-flow template "DNA variant calling with BWA and GATK" --ai
oxo-flow template "ChIP-seq peak calling with MACS2" --ai
oxo-flow template "metagenomics taxonomic classification with Kraken2" --ai

With Reference Materials#

Use --from-url or --from-file to provide protocol documents or example workflows:

# From a URL (protocol, documentation, paper methods)
oxo-flow template "scRNA-seq analysis" --ai \
    --from-url https://satijalab.org/seurat/articles/pbmc3k_tutorial.html

# From a local file
oxo-flow template "custom QC pipeline" --ai \
    --from-file my-protocol.md \
    --from-file data/example_output.txt

# Both URL and file
oxo-flow template "exome analysis" --ai \
    --from-url https://gatk.broadinstitute.org/ \
    --from-file data/cohort_info.csv

Set Output Path#

oxo-flow template "RNA-seq" --ai -o my-pipeline.oxoflow

An existing destination is never clobbered silently — a generated workflow may be a reviewed, hand-edited artifact:

  • interactive terminal: y/N confirmation before anything is generated;
  • non-interactive session (CI, scripts): refused unless --force is passed;
  • --force is explicit consent and skips the prompt.

The guard runs before any paid generation, so a refusal costs nothing and the old file stays byte-for-byte intact. An accepted write goes through the engine-wide staged-write helper (temp file in the same directory, fsync, atomic rename, parent-directory fsync): a crash or write failure leaves the previous workflow complete, never truncated, and a symlinked destination is replaced as an entry rather than written through.

Control AI Behavior#

# Limit correction rounds
oxo-flow template "RNA-seq" --ai --ai-max-retries 5

# Fresh-draw attempts (best-of-N with early exit): attempt 2..N is only paid
# when earlier attempts fail — the deterministic gates decide
oxo-flow template "RNA-seq" --ai --ai-attempts 2

# Opt into the Scientist Team roles (contract + Curator + review)
oxo-flow template "RNA-seq" --ai --ai-team-profile full

Workflow Explanation (ai explain)#

Explain a workflow in plain language — for newcomers reading an inherited pipeline, and for experienced users evaluating one. Three layers:

  1. Overview — what the workflow does, its assay domains, entry and final rules
  2. Step-by-step — each rule's tool, purpose, inputs/outputs, and resources
  3. Scientific review — deterministic, evidence-backed findings (GATK best practices etc.) explained in plain language
oxo-flow ai explain workflow.oxoflow              # beginner-level prose (default)
oxo-flow ai explain workflow.oxoflow --step bwa_mem2_align   # focus one rule
oxo-flow ai explain workflow.oxoflow --level expert          # parameter-level, efficiency-focused
oxo-flow ai explain workflow.oxoflow --json       # machine-readable output

ai explain complements dry-run: dry-run shows the mechanism (what will execute), explain shows the principle (why each step exists). Every fact in the explanation is computed deterministically from the workflow definition plus the embedded knowledge bases (tool table, bioSkills, pipeline graph, scientific preflight). Model prose is advisory and can omit or misstate a detail; the deterministic skeleton and findings are authoritative. The deterministic findings are always printed separately (stderr, or the review array in --json), so consumers must not treat model prose as the evidence surface.

--json emits the deterministic skeleton (rule metadata, I/O, resources, matched knowledge, findings) with model-written prose in dedicated fields — safe for documentation generators. --level defaults to beginner because the audience cannot be inferred from the workflow itself; experts opt in.

Degraded mode (no model)#

ai explain resolves the same provider/model chain as the other AI task surfaces (including the workflow [ai] section) and exits 0 with the deterministic skeleton whenever the model layer is unavailable — provider errors, quota limits, dead endpoints, or explicit disable:

  • OXO_FLOW_AI_PROVIDER=disabled overrides any saved provider and is pinned after the saved config loads — a ~/.oxo-flow/ai_config.json cannot re-enable AI. It produces the skeleton with a AI_DISABLED_BY_ENV structured note on stderr; AI calls fail with AI_NOT_CONFIGURED without contacting a provider.
  • Any other unresolved provider prints the structured degraded reason (AI_CREDENTIAL_MISSING, AI_PROVIDER_INVALID, AI_NOT_CONFIGURED) in the note, so the skeleton always says why model prose is missing.
  • A failed provider call degrades the same way, with the error summarized in the note; the skeleton and its knowledge-base grounding (bioSkills, tool table, pipeline graph) are still emitted in full, and --json consumers still get the JSON contract (prose fields empty).
{
  "workflow_name": "wgs-germline-calling",
  "level": "beginner",
  "domains": ["read-alignment", "variant-calling"],
  "steps": [
    {
      "order": 1,
      "name": "fastp_qc",
      "depends_on": [],
      "inputs": ["raw/{sample}_R1.fastq.gz"],
      "outputs": ["trimmed/{sample}_R1.fq.gz"],
      "threads": 4,
      "tools": ["fastp"],
      "explanation": "Trims adapters and low-quality bases..."
    }
  ],
  "review": [
    {
      "code": "SCI-VQSR-COHORT",
      "rule": "vqsr_snps",
      "message": "VariantRecalibrator trains on the cohort, but only 3 samples are in this run...",
      "suggestion": "stop the pilot before VQSR (-t <rule>) or use hard filtering..."
    }
  ],
  "provenance": {"model": "deepseek-v4-pro", "bio_skills": 562, "pipeline_graph_nodes": 78}
}

Provider failure handling#

The provider layer classifies common model failures; tool-argument handling is fail-closed end to end:

  • Malformed tool-call arguments fail closed: if a model truncates or mangles a tool call's arguments JSON, the parser passes the payload through raw and the orchestrator rejects the call before any tool runs — the model receives a tool-result message carrying the parse error and a re-emit instruction. Arguments are never "repaired" to {} behind the caller's back. Wire-format echoes (Anthropic tool_use.input, Ollama arguments) keep a protocol-valid object fallback, but such a call can no longer execute.
  • Context overflows are classified and recovered: HTTP 400/413 responses with context-window markers map to ContextOverflow; the transcript is compressed (system + recent turns kept, middle turns replaced by a marker) and retried once. A second overflow returns readable guidance instead of burning quota.
  • Tool results are bounded: every tool result entering a transcript is capped at 16 KiB with a UTF-8-safe head+tail truncation marker, so long lookups cannot silently blow up the context window.
  • Offline replay for tests: a scripted provider replays serialized completions (tool calls, errors, delays) through the real code path, so CI covers multi-turn tool-calling and error recovery without an API key.
  • Ollama tool-calls are parsed, not dropped: the Ollama backend now surfaces the model's tool_calls (ids synthesized positionally, object-or-string arguments both accepted), maps prompt_eval_count/eval_count into token usage, and echoes assistant tool-call requests plus tool-role results back in the native request shape. Support still varies by model/daemon version, so an orchestrator run that pairs Ollama with a non-empty tool registry logs a one-time warning.

Configuration#

Global Config (~/.oxo-flow/ai_config.json)#

{
  "provider": "deepseek",
  "model": "deepseek-v4-pro",
  "api_key": "sk-<YOUR-KEY>"
}

Set OXO_FLOW_AI_CONFIG to an explicit file path to redirect this location for both reads and writes. It is the hermetic knob for tests and CI: while it is set the legacy ~/.config/oxo-flow/ai_config.json migration fallback is skipped, so a redirected process cannot touch the user's real config. Unset (the default) keeps the $HOME path above.

Workflow-Level Config ([ai] section in .oxoflow)#

[ai]
enabled = true
max_retries = 5
auto_fix = "ask"    # recovery write mode: "ask" (default) | "always" | "never"
model = "deepseek-v4-flash"
team_profile = "compact"    # "compact" | "full"

auto_fix controls what the recovery path may do with an AI-proposed workflow patch. The mode gates on top of the model's own safety verdict and TOML validation — it never bypasses either. Independently of the mode, every patch is validated before it is written: it must parse as a complete workflow and must not drop anything the original file declared, so a partial "changed portions" response is refused (issue #1110) rather than written as a full replacement. The "must be preserved" set is read from the parsed workflow model, not counted by hand:

  • every rule name in the original must still be present — a same-count rename or rule swap is refused, not only a count drop — and the [[rules]] / [[include]] / [[references]] counts may not shrink;
  • the wildcard fan-out tables [[values]], [[sample_groups]], and [[pairs]] may not shrink in count;
  • no [config] key may disappear.

A rejected fix leaves the workflow byte-for-byte untouched, and an accepted fix is written atomically with a <workflow>.bak guard beside it:

  • ask (default) — prompt y/N before writing on an interactive terminal; non-interactive sessions (CI, scripts) are denied with an explanation, so a headless run can never rewrite the workflow silently
  • always — apply safe fixes automatically (a patch flagged unsafe by the safety assessment is only displayed, never written)
  • never — only report, never modify

An applied fix triggers the verified-repair loop regardless of the mode that authorized it: one bounded verification rerun with the updated workflow, then the outcome lands in the checkpoint's repair_record (see the recovery flow below and run --ai-recover).

Provider and model precedence#

Every AI task surface — template --ai, env create --ai, ai explain, and the AI analyses/recovery of validate, lint, dry-run, debug, report, and run — resolves one config chain before building the provider (AiConfig::resolve_chain_with_env). Later tiers override earlier ones:

  1. Hardcoded defaults
  2. Global config file (~/.oxo-flow/ai_config.json)
  3. Environment (OXO_FLOW_AI_PROVIDER, OXO_FLOW_AI_MODEL, OXO_FLOW_AI_API_URL, and the per-provider credential variables)
  4. Project .oxo-flow/ai.toml (the workflow's directory, or the invocation directory for workflow-less commands such as template --ai)
  5. Workflow [ai] section
  6. CLI flags — no flag currently selects a provider or model; --ai-max-retries and --ai-team-profile override their own settings at this tier

OXO_FLOW_AI_PROVIDER=disabled is the one exception: it is a hard pin above every tier and cannot be overridden by a project or workflow provider. The resolved provider and model are APPLIED to the backend — a workflow that declares provider = "ollama" and model = "qwen3" uses exactly that backend and model even when the shell exports a different provider.

Provider-specific values are resolved for the final provider kind, not carried over from a lower tier: environment credentials for that provider (or OXO_FLOW_AI_API_KEY) outrank a saved config key, and a saved config's key, endpoint, and model are reused only when they belong to the same provider. A workflow switching to claude therefore never sends a saved DeepSeek key, endpoint, or model to Anthropic. If no tier selects a provider, the canonical environment → saved-config → auto-detection chain chooses the backend, so zero-config shell setups keep working; a workflow/project model still applies on top.

The status/inspection surfaces (oxo-flow ai, oxo-flow ai test) report the process environment + saved config only — they take no workflow, so no project/workflow tier exists for them.

Degraded mode and structured reasons#

When AI is enabled ([ai] enabled = true or an explicit --ai flag) but the resolved chain yields no usable provider, commands that can continue without AI (validate, lint, dry-run, debug, report, run's recovery path) print and log a structured reason instead of silently skipping AI:

⚠ AI degraded [AI_CREDENTIAL_MISSING]: provider 'claude' is selected but no
usable credential was found — Set ANTHROPIC_AUTH_TOKEN (or OXO_FLOW_AI_API_KEY),
or run 'oxo-flow ai setup' to save one

The stable codes are AI_DISABLED_BY_ENV (the OXO_FLOW_AI_PROVIDER=disabled pin), AI_PROVIDER_INVALID (an unparseable provider name), AI_CREDENTIAL_MISSING (a provider selected with no usable credential), and AI_NOT_CONFIGURED (nothing selected anywhere). Commands that cannot run without AI (template --ai, env create --ai) fail with the same structured reason on their error path. Provider-type failures mid-request are a separate degradation (documented under provider failure handling).

Generation team profiles#

template --ai runs one generation agent with the engine-gate correction loop (the compact profile, default). The full profile adds three Scientist Team roles around it:

Role Stage Cost What it does
Task contract before generation one small low-temperature call standardizes an under-specified intent into an explicit contract (goal, inputs, outputs, decisions)
Curator before generation zero — deterministic retrieval assembles Bioconda tool candidates, domain procedures, and pipeline-graph transitions from the embedded knowledge bases, so generation spends no paid rounds on knowledge lookups
Independent review after generation one small low-temperature call a fresh evaluator instance judges the artifact against the contract; a request_changes verdict triggers exactly one regeneration pass with the findings

Enable it per call with template --ai --ai-team-profile full, or per project with [ai] team_profile = "full". The review pass is engineered to be unable to regress the outcome (a regeneration replaces the draft only if it also validates) and approves by default — on the measured ablation it triggers on ~7% of runs. Full stays slightly below compact on aggregate gate pass while rescuing scattered hard-tier cells; compact remains the default and the full measurement record lives in eval/frontier/ in the repository.

Environment Variables#

Variable Description Default
OXO_FLOW_AI_PROVIDER Provider: deepseek, claude, openai, ollama, or disabled. An explicit disabled is pinned: it outranks saved config and, in the web server, refuses the runtime-only AI config endpoint (409 AI_DISABLED_BY_ENV), saves persisted settings without applying them (applied_to_runtime: false), and answers the connectivity test with disabled without dialing out unset: auto-detect from credentials; disabled only when none resolve
OXO_FLOW_AI_API_KEY Generic API key (fallback for all providers) —
OXO_FLOW_AI_API_URL Custom API endpoint URL (provider default)
OXO_FLOW_AI_MODEL Model name override (provider default)
OXO_FLOW_AI_CONFIG Explicit AI config file path, used for BOTH reads and writes. When set it is authoritative: the legacy ~/.config/oxo-flow/ai_config.json migration fallback is skipped, so a redirected process can never read or rewrite the $HOME-scoped file. An empty value is ignored; a relative path anchors to the process cwd, and parent directories are created on save. This is the hermetic knob for tests and CI (a web integration test once overwrote the operator's real config) $HOME/.oxo-flow/ai_config.json
OXO_FLOW_AI_SESSION_DIR Directory for archived AI sessions (CLI AI commands and web chat/translate agent-loop runs). Empty = unset. Tests and CI set it to a scratch directory for hermetic runs, so a session archive never lands in the operator's real archive <cwd>/.oxo-flow/ai_sessions when a project-local .oxo-flow exists, else $HOME/.oxo-flow/ai_sessions
OXO_FLOW_AI_MAX_TOKENS Output-token ceiling for the Anthropic Messages backend. Calibrated for thinking-style backends whose reasoning blocks count against max_tokens (e.g. DeepSeek or GLM behind an Anthropic-compatible endpoint) — the old 4096 default truncated before any text was produced 16384
OXO_FLOW_AI_CONTEXT_TOKENS Declared context window for Anthropic-compatible third-party proxies fronting a smaller model (e.g. 131072). The Claude backend clamps max_tokens per request: estimated input size (safety-factored) is subtracted from the window before the output budget is sent, floored at 1024. Unset = no clamping (real Anthropic models size the window server-side) unset
OXO_FLOW_AI_TIMEOUT_SECS Per-request timeout for AI provider calls. A measured GLM thinking round took 145 s — the old 120 s default killed it mid-round. Raise together with OXO_FLOW_AI_MAX_TOKENS on slower endpoints. Also caps the TOTAL budget of the non-streaming web AI JSON routes (/api/chat/send/json, /api/ai/translate), which answer 504 AI_TIMEOUT when it expires — the route budget sits one second under the provider timeout and timeout-class provider errors map to the same 504 300
DEEPSEEK_API_KEY DeepSeek (OpenAI-compatible) —
DEEPSEEK_BASE_URL Custom DeepSeek endpoint https://api.deepseek.com/v1/chat/completions
ANTHROPIC_AUTH_TOKEN Anthropic-compatible API key (the variable Anthropic SDKs and gateway deployments export) —
ANTHROPIC_API_KEY Alias for ANTHROPIC_AUTH_TOKEN —
CLAUDE_API_KEY Alias for ANTHROPIC_AUTH_TOKEN —
ANTHROPIC_MODEL Claude model override claude-sonnet-4-20250514
ANTHROPIC_BASE_URL Custom Anthropic endpoint https://api.anthropic.com/v1/messages
OPENAI_API_KEY OpenAI-compatible API key —
OPENAI_MODEL OpenAI model override gpt-4o
OPENAI_BASE_URL Custom OpenAI-compatible endpoint https://api.openai.com/v1/chat/completions
OLLAMA_HOST Ollama server address (explicit opt-in — no key needed) http://localhost:11434
OLLAMA_MODEL Ollama model override llama3

Zero-config auto-detection: when OXO_FLOW_AI_PROVIDER is unset (or empty) and no saved config exists, oxo-flow looks for the standard provider credentials in this exact order — ANTHROPIC_AUTH_TOKEN / ANTHROPIC_API_KEY / CLAUDE_API_KEY → claude, OPENAI_API_KEY → openai, DEEPSEEK_API_KEY → deepseek, OLLAMA_HOST → ollama. Gateway setups that only export ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URL + ANTHROPIC_MODEL therefore work without any oxo-flow-specific configuration. An explicit OXO_FLOW_AI_PROVIDER (including disabled) always wins; a saved Settings config beats auto-detection; setting a provider without any credential resolves to disabled instead of firing doomed requests, and a whitespace-only credential value counts as absent.


How It Works#

The AI agent combines several embedded knowledge sources, all compiled into the binary at build time. Exact current record counts are exposed by oxo-flow ai and by knowledge_meta.json; do not hard-code a catalog count in a manuscript or release claim.

  1. Tool reference data with resource guidance for common bioinformatics tools.
  2. Bioconda tool records with versions and descriptions, queried on demand through lookup_tool.
  3. bioSkills records with domain procedures, commands, and caveats, matched by assay type or queried through lookup_skill.
  4. Pipeline graph transitions queried through lookup_pipeline for multi-step topology design.
  5. Skill protocol documents fetched one at a time through lookup_doc.

Token efficiency: embedded data is never added to the LLM context wholesale. Only on-demand tool queries (~1 KB per result) and domain-matched skill summaries (≤3 per domain) are injected — the rest stays in the binary until needed. The one deliberate exception is lookup_doc, whose full-protocol response is larger by design (roughly 2-5K tokens per fetched doc) and is still strictly on demand — one skill at a time.

The agent:

  1. Analyzes your intent (assay type, tools mentioned)
  2. Matches relevant bioSkills domains and injects curated expertise
  3. Selects tools from the reference table, verifying current versions via the Bioconda database
  4. Designs a DAG with proper dependencies (optionally consulting the pipeline graph for topology)
  5. Sets resource allocations based on tool requirements
  6. Generates valid .oxoflow TOML
  7. Validates against the engine schema; on failure the errors feed back into the correction loop (bounded by --ai-max-retries), so wrong-dialect output is repaired instead of written with a warning (one shared generation persona across CLI and web)

Custom Skills#

User-defined .skill.toml files (discovered from ~/.oxo-flow/skills and <project>/.oxo-flow/skills) can be activated per workflow via [ai] skills = [...] — their prompt_additions are appended to the system prompt. See Custom Skills.

Session Logs#

Agents operating oxo-flow directly should also follow Agent Safety & Workspace Discipline: inputs are read-only, mutations are snapshotted and journaled, and all probing stays in one scratch tree inside the project.

Every AI interaction is logged to .oxo-flow/ai_sessions/ for audit and debugging:

{
  "id": "20260809-230000-template-a1b2c3d4",
  "command": "template",
  "user_intent": "RNA-seq with STAR and DESeq2",
  "provider": "deepseek",
  "model": "deepseek-v4-pro",
  "total_usage": {
    "prompt_tokens": 1234,
    "completion_tokens": 432,
    "cache_read_tokens": 800,
    "cache_creation_tokens": 200
  },
  "outcome": "success",
  "confidence": 0.91
}

Archive guarantees#

  • Failures are archived too. A run that aborts (provider error, round cap, cancellation, client disconnect) persists outcome: "Failed" with an error reason and the accumulated transcript/usage — the record you need for a post-mortem instead of an empty directory. Successful runs archive outcome: "Success".
  • Writes are crash-safe. Each session is serialized to a temp sibling in the same directory and atomically renamed into place, so a concurrent reader (or oxo-flow ai status scan) always sees a complete JSON document, never a partial write.
  • Fresh archives are never pruned. Retention keeps the newest 200 sessions per directory, but files younger than ten minutes are exempt: a run archived seconds ago — or the session an operator is inspecting — is never rotated out by concurrent writers.
  • Test processes do not touch the operator's archive. Unit tests skip session writes entirely; integration tests point OXO_FLOW_AI_SESSION_DIR at a scratch directory. Set that variable to relocate archives on shared HPC homes or read-only project trees:
export OXO_FLOW_AI_SESSION_DIR=/scratch/$USER/oxo-flow-sessions
  • The scripted test backend cannot be installed in production. Its constructors are compiled out unless the crate is built for tests (cfg(test)) or with the test-scripted Cargo feature (dev-dependencies only), so a real server can never run a stub provider — the Rate limited by scripted archive entries from the browser test came from unit tests writing into the real archive, and that path is now closed.

prompt_tokens is the full prompt bill: on caching-enabled Anthropic-compatible endpoints it includes cache_read_tokens (served from the provider's prompt cache) and cache_creation_tokens (written to it); DeepSeek-native and OpenAI-compatible endpoints report the same split under their own shapes (prompt_cache_hit_tokens and prompt_tokens_details.cached_tokens respectively, folded into cache_read_tokens — DeepSeek has no cache-write counter, so cache_creation_tokens stays 0 there). Token totals stay comparable across providers while the cache split is preserved for cost estimation — cache reads bill below the input rate and cache writes above it. Sessions written before cache accounting carry only the two base counters and still load unchanged.


Provider Comparison#

Provider Model Examples Cost (per 1M tokens) Quality Setup
DeepSeek DeepSeek v4-pro, DeepSeek v4-flash ~$0.14–$0.28 in, ~$0.55–$1.10 out High API key (DEEPSEEK_API_KEY)
OpenAI-compatible Groq LLaMA, Together, Azure Varies High API key
Anthropic-compatible Claude Sonnet 4 Varies ($3–$15 in) Best API key
Local Ollama (llama3, mistral, etc.) Free Moderate Local install

Recommendation: An OpenAI-compatible provider with high throughput (e.g., DeepSeek, Groq) offers the best cost-quality balance for bioinformatics workflows.

Complete Command Reference#

Command AI Flag Auto-Detect What It Does
oxo-flow ai — — Quick status: provider, model, endpoint, connectivity, session count
oxo-flow ai test — — Full self-test: connectivity + generation + analysis (tests the AI integration itself — not a workflow; for workflow testing use oxo-flow test)
oxo-flow ai setup — — Interactive wizard: choose provider, enter key, save config
oxo-flow ai explain WORKFLOW — — Three-layer workflow explanation (overview → steps → scientific review)
oxo-flow ai explain WORKFLOW --step RULE — — Focus the explanation on one rule
oxo-flow ai explain WORKFLOW --level beginner\|expert — — Explanation depth (default beginner)
oxo-flow ai explain WORKFLOW --json — — Machine-readable skeleton + prose (stdout is pure JSON)
oxo-flow template "X" --ai required ❌ Natural language → .oxoflow file
oxo-flow template "X" --ai --from-url URL required ❌ Generate with web page as reference
oxo-flow template "X" --ai --from-file PATH required ❌ Generate with local file as reference
oxo-flow template "X" --ai -o PATH required ❌ Write output to specific path
oxo-flow template "X" --ai --ai-max-retries N required ❌ Override max correction rounds
oxo-flow env create "X" --ai required ❌ Natural language → pinned conda environment YAML (or pixi TOML with --backend pixi)
oxo-flow dry-run WORKFLOW optional ✅ AI analysis if [ai] enabled=true
oxo-flow dry-run WORKFLOW --ai force — Explicit AI override
oxo-flow validate WORKFLOW optional ✅ AI semantic validation
oxo-flow lint WORKFLOW optional ✅ AI best-practice linting
oxo-flow debug WORKFLOW optional ✅ AI command explanation
oxo-flow run WORKFLOW optional ✅ AI error recovery on failure
oxo-flow run WORKFLOW --ai-recover force — Explicit recovery override
oxo-flow run WORKFLOW --ai-max-retries N optional — Max AI recovery attempts when a call fails (default 1)
oxo-flow resume CHECKPOINT --ai-recover required — Diagnose + fix on restart

AI Command Explanation (debug --ai)#

Analyze expanded shell commands with AI:

oxo-flow debug workflow.oxoflow --ai
oxo-flow debug workflow.oxoflow --ai -r specific_rule

The AI explains what each command does and flags potential issues like resource mismatches, missing flags, or incorrect parameter usage.


AI Linting (lint --ai)#

Add semantic best-practice checks beyond the deterministic linter:

oxo-flow lint workflow.oxoflow --ai

AI Workflow Analysis (dry-run --ai)#

Validate workflow correctness, safety, and resource allocation before running:

oxo-flow dry-run workflow.oxoflow --ai

The AI checks:

  • Resource allocations vs. tool recommendations
  • DAG structure (missing dependencies, invalid edges)
  • Safety violations (destructive commands)
  • Environment declarations
  • Best practice adherence

Output includes severity ratings: [ERROR], [WARNING], [INFO].


AI Semantic Validation (validate --ai)#

Combine schema validation with AI-powered semantic analysis:

oxo-flow validate workflow.oxoflow --ai

AI Error Recovery (run --ai-recover)#

When a workflow fails, the AI diagnoses the error and proposes a fix:

oxo-flow run workflow.oxoflow --ai-recover

Recovery flow:

  1. Rule fails → capture error signature
  2. AI matches against known error patterns (OOM, segfault, missing files, etc.)
  3. AI proposes a root cause and bounded patch
  4. The resolved auto_fix mode decides who may write: ask (the default) prompts y/N on an interactive terminal and is denied in non-interactive sessions, always auto-applies safe fixes, never only reports. In every mode the generated TOML must still validate as a complete workflow before it is written; a patch flagged unsafe by the safety assessment is only displayed
  5. A proposed fix is validated before it is written, and a rejected fix leaves the workflow byte-for-byte untouched. The patch must parse as a complete workflow (WorkflowConfig::parse) AND must not drop sections the original file already had — if the response is a partial document (for example a [workflow]-only or [[rules]]-only fragment) that would discard the original's rules, [[include]] entries, or [[references]], the fix is rejected with a precise diagnostic and nothing is written. This guards against a model returning "only the changed portions" and clobbering a full pipeline
  6. An accepted fix is written atomically (temp file in the same directory, then rename) and the pre-fix file is preserved twice: the session archive (archive_before_modify) and a sibling <workflow>.bak. A repair is not described as fixed until the complete workflow validates, the applied diff is reviewed, and a rerun verifies its outputs
  7. Verified repair (issue #1164): when the fix is written, the engine prints REPAIR_APPLIED session_id=<id> and attempts ONE bounded verification rerun with the updated workflow (run <workflow> --resume-failed --no-ai-recover — succeeded rules stay skipped, failed rules re-run). The rerun outcome is narrated with the stable REPAIR_RERUN_SUCCEEDED / REPAIR_RERUN_FAILED / REPAIR_RERUN_SKIPPED prefixes and recorded in the checkpoint's repair_record ({applied, session_id, rerun_attempted, rerun_succeeded, detail, timestamp}); a rerun that completes the workflow exits 0, a failed one keeps the ordinary failure path. The rerun carries --no-ai-recover, so it can never start another repair cycle — the REPAIR_* prefixes are a machine-readable contract, never reworded

See the CLI/AI blockers in docs/superpowers/audits/industrial-scientific-audit-ledger.md.


Embedded Knowledge Freshness#

The knowledge sources are compiled into the binary at build time, so they only change when the binary is rebuilt. Every data file is documented by crates/oxo-flow-ai/src/knowledge/knowledge_meta.json — a plain JSON document listing each source's record count, generation timestamp, and whether it is auto-updated or manually curated:

{
  "sources": {
    "bioconda_tools": {
      "count": 6688,
      "url": "https://conda.anaconda.org/bioconda/channeldata.json",
      "excluded": 6225,
      "data_file": "bioconda_tools.jsonl",
      "generated_at": "2026-11-16T10:44:43Z",
      "auto": true
    }
  },
  "generated_at": "2026-11-16T11:04:56Z"
}

count always equals the number of records in data_file — a drift-guard test fails the build if the two ever diverge.

Seeing freshness#

oxo-flow ai prints a Knowledge freshness section: per-source record count, generation date, staleness in days, and the auto/manual origin. Auto-updated sources older than 60 days are flagged STALE. The lookup_tool tool response likewise appends a freshness note (data date + record count), so AI agents can weigh how current the embedded database is.

Update cadence and the Knowledge Refresh workflow#

A scheduled GitHub Action — the Knowledge Refresh workflow (.github/workflows/refresh-knowledge.yml) — runs on the 1st and 16th of each month at 03:00 UTC, and can be dispatched manually at any time (Actions → Knowledge Refresh → Run workflow). It re-pulls each upstream source, rewrites the JSONL data files only when content changed, and opens a reviewed PR (chore(knowledge): automatic knowledge refresh <date>) with per-source entry-count changes. A run that finds no data changes completes green without a PR. A failing upstream source is tolerated — the other sources still refresh and the failure is reported in the PR body.

Staleness gate#

The release pipeline rejects a dispatch release when any auto: true source is older than 60 days (twice the 16-day cadence, tolerating one missed run). The gate lives in ci.yml's version-sync job, so a stale snapshot is blocked before any version bump or tag is created. Manually curated sources (auto: false) are exempt — their freshness is the maintainer's call. If a release is blocked, run the Knowledge Refresh workflow, merge its PR, and re-dispatch the release.


Troubleshooting#

"AI provider not configured"#

# Check your configuration
oxo-flow ai                    # Shows provider status and connectivity
echo $OXO_FLOW_AI_PROVIDER     # Should not be empty or "disabled"

# Set up any provider
export OXO_FLOW_AI_PROVIDER=<provider>
# then the matching credential:
#   deepseek → DEEPSEEK_API_KEY, openai → OPENAI_API_KEY,
#   claude → ANTHROPIC_AUTH_TOKEN, ollama → OLLAMA_HOST (no key)

"AI response did not contain valid TOML"#

The AI returned a response without valid .oxoflow TOML content. This is rare — try again with a more specific description.

Rate Limiting#

If you see rate limit errors, wait a few seconds and retry. For production use, consider upgrading your API plan or switching to a provider with higher rate limits.


Roadmap#

Phase Features Status
Phase 1 AI template generation Implemented but unproven
Phase 2 AI dry-run + validate analysis Implemented but unproven
Phase 3 AI error recovery (--ai-recover) Prototype / partial-file replacement refused and fix written atomically with a .bak guard (#1110); rerun still unverified
Phase 4 Scope-level AI config, AI plugin types (trait surface only — no loader, see oxo_flow_ai::plugin) Prototype / workflow-scoped policy is not fully enforced
Phase 5 MCP/Skill ecosystem Prototype / generic MCP token release is origin-gated via OXO_FLOW_MCP_TRUSTED_ORIGINS and model-initiated outbound fetches require a data-release decision (OXO_FLOW_AI_FETCH_TRUSTED_ORIGINS pre-authorizes exact origins; non-interactive sessions refuse) (#1123, see custom skills)
Phase 6 Workflow explanation (ai explain) Implemented but unproven
Phase 7 Provider failure handling Implemented but unproven; malformed tool arguments are fail-closed (AI-07)

See the full design spec at docs/superpowers/specs/2026-08-09-ai-native-cli-design.md (repository root, not included in the published docs) for architecture details.