{"slug": "ecaa-workflow-deterministic-workflow-compiler-for-fair-bioinformatics", "title": "ECAA-workflow: deterministic workflow compiler for FAIR bioinformatics", "summary": "The ECAA-workflow project released a deterministic offline compiler that transforms natural-language bioinformatics analysis descriptions into self-contained RO-Crate packages. The tool includes a conversational shell, execution harness, and validator for machine-checkable consistency, targeting FAIR bioinformatics practices. It supports Linux x86-64 with macOS for development and Windows via WSL2.", "body_md": "A deterministic, offline compiler that turns a natural-language description of a bioinformatics analysis into a self-contained, agent-executable [RO-Crate](https://www.researchobject.org/ro-crate/) package — with a full-lifecycle conversational shell wrapped around the executing package.\n\nThe compiler classifies the intake, selects an archetype, builds a task DAG, emits a package, and an execution harness drives an agent (Claude Code, a shell script, anything callable with a package path) against the emitted DAG. The emitted package is an **ECAA** (Evidence-Carrying Analysis Artifact) v0.2 package — a typed RO-Crate that carries, alongside the analysis itself, the claims it supports, the evidence backing each claim, and the decision record that produced them. An embedded **ECAA validator** checks the package against a machine-checkable contract over those subgraphs. Emit-time validation defaults to pure-Rust JSON Schema (`schema_only`\n\n) and is **advisory (warn-only)** on a plain emit unless `ECAA_VALIDATION_BLOCK_ON_FAIL=1`\n\n; the local conformance gate (`make conformance`\n\n, `ECAA_CONFORMANCE_MODE=1`\n\n) runs it block-on-fail. The contract establishes machine-checkable **consistency** between an analysis's claims, evidence, decisions, and execution provenance — it does **not** establish biological validity; treat verdicts as a hygiene floor, not a quality ceiling.\n\n| Component | Crate / dir | Role |\n|---|---|---|\n| Compiler | `crates/{core, cli}` |\nClassifier → DAG → emitter. Synchronous, no LLM dependency. |\n| Conversation shim | `crates/conversation` |\nClosed tool vocabulary wraps the compiler. LLM is a UX shim only. |\n| Chat server | `crates/server` |\nAxum HTTP + SSE backend at `/api/chat/*` and `/api/git/*` . |\n| Execution harness | `crates/harness` |\nLoops an agent subprocess against ready tasks. `Local` / `Mock` / `AWS` / `SLURM` executors. |\n| ECAA validator | `crates/{ecaa-conformance, ecaa-types}` + `docs/ecaa-spec/` |\nEmits + validates the ECAA conformance contract. `ecaa-conformance` re-exports core's public API and is the conformance harness a second implementer runs against their own packages — not an independent reimplementation of core. |\n| Web UI | `ui/` |\nReact 18 + Vite + TypeScript chat surface. |\n\nCurrent ECAA profile IRI: `https://w3id.org/ecaa/v0.2`\n\n. The active spec files are in [ docs/ecaa-spec/](/SuLab/ECAA-workflow/blob/main/docs/ecaa-spec):\n\n`v0.2.md`\n\n, `ecaa-v0.2.ttl`\n\n, `ecaa-v0.2.shacl.ttl`\n\n, and `ecaa-v0.2.jsonld`\n\n.Linux x86-64 is the primary supported target. macOS works for dev. Windows requires WSL2.\n\n```\n# 1. System tools\nsudo apt-get install -y build-essential pkg-config libssl-dev mold git curl   # Debian/Ubuntu\n# or: sudo dnf install -y @development-tools openssl-devel mold git curl       # Fedora/RHEL\n# or: brew install mold openssl@3 pkg-config                                    # macOS\n\n# 2. Rust toolchain (auto-installs the pinned channel from rust-toolchain.toml)\ncurl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y\nsource \"$HOME/.cargo/env\"\n\n# 3. Cargo dev tools\ncargo install --locked cargo-nextest cargo-hakari\n\n# 4. Node.js 20+ (for the UI + Playwright)\n# install per your platform; verify: node --version  # ≥ 20\n\n# 5. Build everything\nmake build           # Rust workspace (debug)\nmake install         # binaries to ~/.cargo/bin\n(cd ui && npm install)\n```\n\n`make doctor`\n\nprints toolchain readiness; `make help`\n\nlists targets.\n\nTwo terminals:\n\n```\n# terminal A — chat server on :3000\nmake dev-server\n\n# terminal B — Vite dev UI on :5173 (proxies /api/* to :3000)\nmake dev-ui\n```\n\nExecution requires the installed harness binary.`make dev-server`\n\n/`make dev-ui`\n\nrun from source (`cargo run`\n\n/ Vite), so they work without`make install`\n\n. But theStart executionbutton spawns the`ecaa-workflow-harness`\n\nbinaryby name from`PATH`\n\n(override with`ECAA_HARNESS_BIN_PATH`\n\n). If you skipped`make install`\n\n(Setup step 5), execution fails with`failed to spawn harness: No such file or directory`\n\n; run`make install`\n\nto fix it.\n\nThe chat surface boots in offline mode without an API key (the UI renders but assistant turns are mocked). For LLM-mediated chat:\n\n```\nexport ECAA_ANTHROPIC_API_KEY=<your key>\nmake dev-server\n```\n\nFor local production configuration, start from [ .env.example](/SuLab/ECAA-workflow/blob/main/.env.example). Its active defaults are loopback/local and durable under\n\n`$HOME/.ecaa-workflow`\n\n; live API, eval, debug, AWS, SLURM, and external-validator knobs are commented until deliberately enabled.Smoke-test the compiler against a bundled scenario:\n\n```\necaa-workflow intake \\\n  --input testdata/scenarios/01-bulk-rnaseq-ibd/request.md \\\n  --output /tmp/ibd-package\necaa-workflow dag --package /tmp/ibd-package\nmake test            # cargo test --workspace\nmake test-ui         # Vitest + axe a11y\nmake check           # test + tsc --noEmit\nmake e2e-playwright  # mocked Playwright tier\n```\n\n**Compiler is synchronous.**`tokio`\n\nis allowed in`server`\n\n,`conversation`\n\n, and`cli`\n\n(for`serve`\n\nonly). Never in`core`\n\nor`harness`\n\n. Harness uses`ureq`\n\n(sync).**Deterministic output.** Emitted packages are byte-reproducible. Use`BTreeMap`\n\n, not`HashMap`\n\n. Avoid timestamps and random IDs outside`uuid_short()`\n\n.**LLM as UX shim.** Closed tool vocabulary (`Tool::COUNT`\n\nasserted at compile time). High-impact actions are gated by deterministic server state, not LLM inference.**Confirmation discipline.**`emit_package`\n\nreturns`PreconditionFailure`\n\nunless`session.user_confirmed == true`\n\n. The button click is a server-side action the LLM observes only via`get_session_state`\n\n.**ECAA conformance.** Every normal emitted package carries the eight required ECAA v0.2 sidecars:`runtime/intake-conversation.jsonl`\n\n,`runtime/decisions.jsonl`\n\n,`runtime/validation-reports.jsonl`\n\n,`runtime/proofs.jsonl`\n\n,`runtime/claim-verification.json`\n\n,`runtime/verifier-decisions.jsonl`\n\n,`runtime/assumptions.jsonl`\n\n, and`runtime/audit-proof-report.json`\n\n. There is no reduced ECAA mode switch;`ECAA_ABLATE_*`\n\nflags are the only code-backed way to emit non-conformant control artifacts.\n\n`config/`\n\nis the source of truth for modalities, archetypes, atoms, compute profiles, gene panels, plot affordances, and downstream-policy contracts. `config/archetypes/`\n\nand `config/stage-atoms/`\n\ncarry their own READMEs. Runtime environment variables are catalogued in [ .env.example](/SuLab/ECAA-workflow/blob/main/.env.example).\n\nUser guide: [ USERS.md](/SuLab/ECAA-workflow/blob/main/USERS.md). Methods summary:\n\n[. Contributor guide:](/SuLab/ECAA-workflow/blob/main/METHODS.md)\n\n`METHODS.md`\n\n[. ECAA spec:](/SuLab/ECAA-workflow/blob/main/CONTRIBUTING.md)\n\n`CONTRIBUTING.md`\n\n[.](/SuLab/ECAA-workflow/blob/main/docs/ecaa-spec)\n\n`docs/ecaa-spec/`\n\nApache-2.0 — see [ LICENSE](/SuLab/ECAA-workflow/blob/main/LICENSE).", "url": "https://wpnews.pro/news/ecaa-workflow-deterministic-workflow-compiler-for-fair-bioinformatics", "canonical_source": "https://github.com/SuLab/ECAA-workflow", "published_at": "2026-07-01 13:32:59+00:00", "updated_at": "2026-07-01 13:51:06.127715+00:00", "lang": "en", "topics": ["developer-tools", "machine-learning", "artificial-intelligence"], "entities": ["ECAA-workflow", "RO-Crate", "Claude Code", "Axum", "React", "Vite", "TypeScript", "SLURM"], "alternates": {"html": "https://wpnews.pro/news/ecaa-workflow-deterministic-workflow-compiler-for-fair-bioinformatics", "markdown": "https://wpnews.pro/news/ecaa-workflow-deterministic-workflow-compiler-for-fair-bioinformatics.md", "text": "https://wpnews.pro/news/ecaa-workflow-deterministic-workflow-compiler-for-fair-bioinformatics.txt", "jsonld": "https://wpnews.pro/news/ecaa-workflow-deterministic-workflow-compiler-for-fair-bioinformatics.jsonld"}}