vela

SDK reference

Build against the substrate.

The CLI, the Rust crates, the Python and TypeScript reducer bindings, and the hub HTTP API. Everything a researcher or research engineer needs to integrate without contacting the team.

§1

vela CLI

The vela binary is the canonical write surface. Every command produces a signed event that any reducer in the world can replay byte-for-byte. New users should start with /quickstart for the end-to-end loop; this section is the reference.

vela frontier new

Scaffold a publishable frontier.json.

vela frontier new --name <NAME> [--description <TEXT>] [--force] <PATH>

vela init

Initialize a local .vela/ repo (not directly publishable; use frontier new for hub-bound work).

vela init [--name <NAME>] [<PATH>]

vela finding add

Add a finding to a frontier. Without --apply it lands as a pending proposal in the inbox.

vela finding add <FRONTIER> \
    --assertion <TEXT> \
    --author <ACTOR-ID> \
    [--type mechanism|therapeutic|diagnostic|epidemiological|...] \
    [--source <LABEL>] [--source-type published_paper|preprint|...] \
    [--confidence 0.0-1.0] \
    [--evidence-type experimental|observational|...] \
    [--entities name:type,name:type,...] \
    [--doi <DOI>] [--pmid <PMID>] [--year <YYYY>] \
    [--apply]

vela finding supersede

Supersede an existing finding with a revised content-addressed claim. Old finding flagged superseded; new finding gets an auto-injected supersedes link.

vela finding supersede <FRONTIER> \
    --supersedes <FINDING-ID> \
    --assertion <TEXT> \
    --author <ACTOR-ID> \
    [--confidence 0.0-1.0] \
    [--apply]

vela link add

Typed edge between two findings. Cross-frontier targets use vf_…@vfr_… form.

vela link add <FRONTIER> \
    --from <FINDING-ID> \
    --to <FINDING-ID> \
    --type supports|depends|contradicts|narrows|supersedes

vela sign

vela sign generate-keypair [--out <DIR>]
vela sign apply <FRONTIER> --private-key <PATH>
vela sign verify <FRONTIER> [--public-key <PATH>]
vela sign threshold-set <FRONTIER> <FINDING-ID> --to <N>

vela actor add

Register an Ed25519 public key for a stable actor identity.

vela actor add <FRONTIER> <ACTOR-ID> --pubkey <HEX> [--orcid <ORCID>]
vela actor list <FRONTIER>

vela registry

Publish, list, pull, and mirror frontier manifests.

vela registry publish <FRONTIER> \
    --owner <ACTOR-ID> --key <PRIVATE-KEY> \
    --locator <URL> [--to <HUB>]

vela registry list [--from <HUB>]
vela registry pull <VFR-ID> [--from <HUB>] --out <PATH>
vela registry mirror <VFR-ID> --from <HUB> --to <HUB>

vela serve --workbench

Launch the local workbench web app against a Vela repo.

vela serve <FRONTIER> --workbench --http <PORT>

Agent commands (Vela's bundled agents)

LLM-backed pipelines that walk source material and write finding.add proposals tagged with an AgentRun record (full schema in /spec § 4 · AgentRun). Reviewers accept via the inbox; nothing becomes canonical without a separate signed finding-accepted from a registered reviewer.

vela scout         <FOLDER> --frontier <PATH>   # Literature Scout (PDFs)
vela compile-notes <VAULT>  --frontier <PATH>   # Markdown / Obsidian
vela compile-code  <ROOT>   --frontier <PATH>   # Jupyter / Python / R
vela compile-data  <ROOT>   --frontier <PATH>   # CSV / TSV
vela review-pending      --frontier <PATH>   # Reviewer Agent
vela find-tensions       --frontier <PATH>   # Contradiction Finder
vela plan-experiments    --frontier <PATH>   # Experiment Planner

Agent SDK — third-party integration

Status: not yet shipped as language packages. The CLI agents above are Vela's bundled pipelines and reference implementations. Third-party agents should write proposal JSON or shell out to the binary until dedicated Python and TypeScript packages are released.

  • vela-py (Python) — vela.publish_proposal(event, agent_run=…) signs a finding-drafted event in-process.
  • vela-ts (TypeScript) — same surface, ESM module for Node and edge runtimes with the same wire-format guarantees as the existing vela_reducer.mjs.

The hub read API is event-first today. Direct event append semantics remain a conformance target for agent traffic and are specified in /spec § 7 · agent traffic.

Causal reasoning

Pearl-tier queries against the link graph.

vela causal audit       <FRONTIER>                     # per-finding identifiability
vela causal effect      <FRONTIER> <SOURCE> --on <TGT>  # back-door / front-door (Pearl L2)
vela causal counterfactual <FRONTIER> <SRC> --target <TGT> --set-to <0..1>  # twin-network (L3)
vela causal graph       <FRONTIER>                     # print the directed link graph

Cross-frontier composition

vela frontier add-dep    <FRONTIER> --vfr-id <ID> --snapshot <HASH>
vela frontier refresh-deps <FRONTIER>                  # re-pin to current hub snapshots
vela bridge              <A.json> <B.json>              # cross-frontier hypotheses
vela bridges confirm     <FRONTIER> <BRIDGE-ID> --reviewer <ID>
§2

Rust crates

The canonical reducer is implemented in Rust. Three crates compose the workspace.

vela-protocol
The protocol types: Event, Finding, EvidenceObject, Correction, Signature, canonical-JSON serialization, hash-of-canonical signing surface. Pure no_std-compatible types with serde.
vela-reducer
The deterministic state machine. fn reduce(events: &[Event]) -> Frontier. Byte-identical output across machines and versions for any given event log. Test fixtures verify byte-equality with the Python and TypeScript reducers.
vela-hub
The HTTP server (axum) that accepts signed events, persists the log, and serves the canonical state. The vela-hub binary is what runs at vela-hub.fly.dev.

Add the crates to a Rust project from the workspace root.

[dependencies]
vela-protocol = { git = "https://github.com/vela-science/vela", branch = "main" }
vela-reducer  = { git = "https://github.com/vela-science/vela", branch = "main" }

Replay an event log from disk:

use vela_protocol::Event;
use vela_reducer::reduce;

let events: Vec<Event> = std::fs::read_dir(".vela/events")?
    .map(|e| serde_json::from_slice(&std::fs::read(e?.path())?))
    .collect::<Result<_, _>>()?;

let frontier = reduce(&events);
println!("findings: {}", frontier.findings.len());
§3

Python reducer

Stdlib-only verifier and reducer. Designed to be auditable in one sitting and installable with no transitive dependencies — the same constraint that lets the thirty-second proof at /try run on any laptop. 

from vela_reducer import reduce, verify_signature

with open(".vela/events/0001-finding-drafted.json") as f:
    events = [json.loads(line) for line in f]

frontier = reduce(events)
assert verify_signature(events[0])
print(f"findings: {len(frontier['findings'])}")

Source at vela_reducer.py on this domain. Stdlib-only. Auditable end-to-end in roughly 600 lines.

§4

TypeScript reducer

ESM module, runs in node and modern browsers without polyfills. Used by the workbench to replay state in the client and verify signatures locally. 

import { reduce, verifySignature } from "/vela_reducer.mjs";

// v0.55.1: substrate is fetched from the hub, which 302-redirects to
// the content-addressed CDN blob. One round trip; bytes never touch
// the hub VM.
const frontier = await fetch("https://vela-hub.fly.dev/entries/vfr_bd91/snapshot")
    .then(r => r.json());

const replayed = reduce(frontier.events);
const allValid = (frontier.events ?? []).every(verifySignature);
console.log(`findings: ${replayed.findings.length}, valid: ${allValid}`);

Source at vela_reducer.mjs. ESM module, no build step required.

§5

Hub HTTP API

The canonical hub at vela-hub.fly.dev. No authentication, no rate limiting, CORS open. The signature scheme is the bind.

GET /entries

List all known frontier entries.

curl https://vela-hub.fly.dev/entries

GET /entries/{vfr_id}

Get a single frontier's signed manifest and event count.

GET /entries/{vfr_id}/events

Read the canonical event log with cursor pagination.

curl "https://vela-hub.fly.dev/entries/{vfr_id}/events?since=<event_id>&limit=100"

GET /entries/{vfr_id}/snapshot

Derived reduced state. Hubs may redirect this export to content-addressed object storage.

POST /entries

Publish a signed registry entry and optional substrate export.

vela registry publish <FRONTIER> \
    --owner <ACTOR-ID> --key <PRIVATE-KEY> \
    --to https://vela-hub.fly.dev

The hub validates the manifest signature and hashes before promoting a live frontier row.

GET /.well-known/vela

Discovery endpoint. Returns hub capabilities, supported protocol versions, signing algorithm (always ed25519-canonical-json-v1), and admin contact.

§6

Event schema

Every event is canonical-JSON, signed with Ed25519 over the byte-canonical serialization (no pre-hash). The four primitive event types share a common envelope. 

{
  "v": 1,                              // protocol version
  "id": "ev_8a3e...",                  // content-addressed event id
  "ts": "2026-05-02T15:42:01Z",        // ISO-8601 UTC, monotonic per actor
  "actor": "did:key:z6Mk...",          // signer's verifying key
  "kind": "finding-drafted",           // event type
  "frontier": "vfr_bd91...",           // target frontier
  "payload": { ... },                  // type-specific body
  "sig": "ed25519:8c2a9f..."           // signature over canonical bytes
}

Full schema documentation, including the payload shape for each event kind, lives in the protocol spec at /spec. The primitives appendix walks the information model in prose.