VELLA is the decision layer between an AI agent or autonomous system proposing an action and that action being taken. It sits where alignment, input safety, and IAM don't: at the specific moment an autonomous system is about to act, under a specific policy, with specific evidence in hand.
Given a proposed action and an evidence mask, VELLA returns ALLOWED or DENIED deterministically and emits a cryptographically signed proof bundle. The bundle can be verified offline by any third party with only the bundle and a public key — no access to VELLA, the agent, or the originating system required.
This is a reference implementation, MIT-licensed. It's designed to be the primitive that agent frameworks, audit pipelines, and compliance systems build on.
This repository demonstrates the core VELLA primitive:
- Before an action runs, the caller submits a proposed intent, such as
DATA_EXPORT,ESCALATE_PRIVILEGE, orEXECUTE_CHANGE, along with evidence indicators. - VELLA evaluates that request against policy.
- VELLA returns a deterministic
ALLOWEDorDENIEDdecision. DENIEDis fail-closed: the caller must not execute the action.- If signing is enabled, VELLA emits a proof bundle.
- That proof bundle can be verified offline using the tools in this repo.
VELLA decides whether an action is authorized before it runs. The calling system remains responsible for carrying out — or blocking — the action.
The SDK is designed for in-process, low-latency adjudication; the authority decision can sit directly on the action path rather than being deferred to post-hoc logging.
Start here:
- An Inspectable Substrate for AI Governance — the conceptual argument (~14 min read)
- Quickstart — Node or Python SDK, working example in 2 minutes
- Threat model — what VELLA does and does not protect against
- AI-assisted integration prompting — prompt patterns for using AI coding agents to integrate VELLA without outsourcing authority decisions
npm install @vellacognitive/vella-sdkpip install vella-sdkThe Node package has no runtime dependencies. The Python package depends only on cryptography for ECDSA signing. Python 3.10+ required; Node 18+ required.
Python applications with an application-supplied policy can use the stable from vella import create_evaluator API. See the Python SDK custom-policy documentation.
Releases on npm and PyPI are published via Trusted Publisher (OIDC) from this repository's tagged GitHub Releases. The npm package carries provenance attestations you can verify with npm audit signatures.
import { govern } from "@vellacognitive/vella-sdk";
import fs from "node:fs";
const signingKey = fs.readFileSync("./example-signing.key", "utf8");
const result = govern({
intent: "EXECUTE_CHANGE",
evidenceMask: 1,
proof: { signingKey },
});
console.log(result.decision, result.reasonCode);
console.log(result.proofBundle.envelope_id);from vella import govern
signing_key = open("./example-signing.key", "r", encoding="utf-8").read()
result = govern(
intent="EXECUTE_CHANGE",
evidence_mask=1,
proof_signing_key=signing_key,
)
print(result["decision"], result["reason_code"])
print(result["proof_bundle"]["envelope_id"])Contributors and anyone running an unreleased revision against their own code path:
git clone https://github.com/vellacognitive/vella-substrate.git
cd vella-substrate/sdk/node
npm ci
npm testTo install the source checkout into another project, npm pack produces a tarball that npm install /path/to/tarball.tgz will accept.
git clone https://github.com/vellacognitive/vella-substrate.git
cd vella-substrate/sdk/python
python3.10 -m venv .venv # 3.10+ required; replace with python3.11/3.12 as available
. .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev]"
pytest
ruff check .
mypy --strict vella/- SDK:
sdk/node/andsdk/python/embedded SDKs for local adjudication + signed proof bundles
- Spec:
spec/icd.md,spec/threat-model.md,spec/reason-codes.md, andspec/schemas/
- Verifiers:
verify/verify.js,verify/verify.py,verify/verify.shstandalone proof-bundle verifiers
- Test vectors:
test-vectors/valid/andtest-vectors/tampered/for verifier CI and audit workflows
- Benchmarks:
benchmarks/reproducible latency harness for both SDKs — seebenchmarks/README.mdfor methodology and reference results
The VELLA SDK in this repository is one of several VELLA components. It runs in-process inside Node.js and Python applications and is designed for agent hooks, CI/CD gating, edge compute, research notebooks, and any other context where a library-level adjudicator with microsecond latency is the right fit.
For enterprise service mesh deployments, polyglot environments, network-boundary enforcement, Kubernetes admission control, or multi-tenant adjudication, the runtime service and sidecar adapter (available via commercial license from Vella Cognitive, LLC) are the appropriate components.
See DEPLOYMENT.md for the complete deployment scope and the table of technical specifications.
For commercial licensing or integration services: agent@vellacognitive.com
node verify/verify.js examples/allowed-bundle.json examples/example-signing.pub
python verify/verify.py examples/allowed-bundle.json examples/example-signing.pub
bash verify/verify.sh examples/allowed-bundle.json examples/example-signing.pubThis repository is released under the MIT License.
See SECURITY.md.
If you reference VELLA in research, writing, or technical documentation, please cite:
Wilson, M. (2026). An Inspectable Substrate for AI Governance. Zenodo. https://doi.org/10.5281/zenodo.19738376
The conceptual argument accompanying this release is available as a companion essay:
Wilson, M. (2026). An Inspectable Substrate for AI Governance. Vella Cognitive. https://vellacognitive.com/research/an-inspectable-substrate-for-ai-governance
Machine-readable citation metadata is available in CITATION.cff.
See CONTRIBUTING.md and CODE_OF_CONDUCT.md.