Vela Python client
Cross-implementation reducer + loader for the Vela protocol. The
authoritative implementation is the Rust workspace under
crates/vela-protocol/; this Python module mirrors the kernel
behavior so a third-party Python tool can replay a frontier's
event log and load a split-repo without depending on the Rust
binary.
The cross-impl invariant is: given the same canonical event log and the same Carina kernel digest, the Rust reducer and the Python reducer produce byte-equivalent finding-state digests. This is the load-bearing property that lets Vela claim "the protocol is implementation-portable."
What's here
-
vela_reducer.py: the reducer dispatch. Accepts a canonicalStateEventJSON dict + a Project state dict, applies the reducer arm for the event'skind, mutates state in place. Mirrorscrates/vela-protocol/src/reducer.rs::apply_event. -
vela_loader.py: the split-repo loader. Reads.vela/findings/,.vela/events/,.vela/proposals/, plusfrontier.yaml, populatesproject.dependenciesfrom the v0.59frontiers_v2schema, replays events through the reducer. Mirrorscrates/vela-protocol/src/repo.rs::load_vela_repo. Yaml is parsed viapyyamlif present; otherwise a hand-rolled parser narrow to the manifest's exact shape. -
tests/test_loader_frontiers_v2.py: integration test asserting the loader produces the same dependency state + finding state the Rust loader does on a real frontier (projects/early-ad-biomarker-calibration).
Usage
from vela_loader import load_frontier_repo
project = load_frontier_repo("/path/to/projects/early-ad-biomarker-calibration")
# project is a dict with keys:
# project: { name, description, dependencies }
# frontier_id, findings, events, proposals
# review_events, confidence_updates, manifest
# negative_results, trajectories, artifacts, evidence_atoms
print(f"frontier: {project['project']['name']} ({project['frontier_id']})")
print(f"findings: {len(project['findings'])}")
print(f"events: {len(project['events'])}")
print(f"deps: {len(project['project']['dependencies'])}")
What's NOT here (honest gaps)
The Python loader does not currently rehydrate every field the Rust loader does. Specifically missing:
vela.lock(lockfile parsing).actors.json,peers.json(federation surfaces).proof-state.json.signatures/,replications/,datasets/,code-artifacts/,predictions/,resolutions/,artifacts/.- The v0.55 trajectories+nulls materialization.
- The v0.56 evidence-atom locator materialization.
.vela/links/manifest.jsonredistribution.project::recompute_stats.
These are real gaps. The cross-impl invariant currently holds at the finding-state-digest level only; full Project parity is a follow-on cycle. Anyone implementing a third Vela language binding should target the same subset first and document their gaps as honestly.
Running the test
The test runs without pytest if needed:
python3 clients/python/tests/test_loader_frontiers_v2.py
Or with pytest:
python3 -m pytest clients/python/tests/
Cross-impl correctness
The fixture harness is Rust-side at
crates/vela-protocol/tests/cross_impl_reducer_fixtures.rs.
Each fixture builder generates an event log; the test exports
the same logs to JSON for the Python reducer to replay; the
finding-state digests must match byte-for-byte. The test file's
fixture_coverage_includes_every_reducer_arm assertion
verifies every kind in REDUCER_MUTATION_KINDS has a fixture
builder. New kinds added to the Rust reducer must be reflected
in this Python module (a no-op match arm is sufficient if the
kind doesn't mutate finding state) and in the fixture builders.
Doctrine
The Python loader is a mirror, not the spec. When the Rust and
Python reducers disagree, the Rust implementation is
authoritative; the Python side is the bug. The cross-impl test
catches the disagreement; the spec at docs/PROTOCOL.md
documents the canonical behavior.
No silent edits. No event-log mutation. No version-skew silently glossed; if a new kind appears in the event log that the Python dispatch doesn't know, the loader raises rather than silently dropping the event.
1 maintainer
Release files for vela-state 0.160.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| vela_state-0.160.0.tar.gz | 23.8 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| vela_state-0.160.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 45.7 kB
Release files / vela_state-0.160.0.tar.gz
| Download URL | vela_state-0.160.0.tar.gz |
|---|---|
| Size | 23.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c95d5cea980aca185af424593ec41ab5a6d4e0ab1325f227d983fd6784a87c4c
|
|
BLAKE2b-256 checksum How to use checksums |
ce07460a6f0c5e6b5d4afd10a15434ab77ed6bad902b3b88c25f57a74dcaa943
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
Release files / vela_state-0.160.0-py3-none-any.whl
| Download URL | vela_state-0.160.0-py3-none-any.whl |
|---|---|
| Size | 21.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5fa2edc6d8ccf11c7a3a75419443b7e074a0f5465fd2c56e32e153c5617e127d
|
|
BLAKE2b-256 checksum How to use checksums |
8ec9240e15384a828067ddd19b36234e238f927b1c769889bea524aea5a8b0cc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.9
|
