vella-sdk 1.0.1__tar.gz

vella_sdk-1.0.1/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: vella-sdk
+Version: 1.0.1
+Summary: VELLA — deterministic pre-execution governance substrate. SDK for producing signed decision records.
+Author-email: "Vella Cognitive, LLC" <agent@vellacognitive.com>
+License: MIT
+Project-URL: Homepage, https://vellacognitive.com/research/an-inspectable-substrate-for-ai-governance
+Project-URL: Repository, https://github.com/vellacognitive/vella-substrate
+Project-URL: Issues, https://github.com/vellacognitive/vella-substrate/issues
+Keywords: vella,governance,ai-safety,pre-execution,policy,audit,proof-bundle
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# vella-sdk
+
+Python SDK for deterministic pre-execution adjudication and signed proof-bundle generation.
+
+## Install
+
+```bash
+pip install vella-sdk
+```
+
+## From source (development)
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy --strict vella/
+```
+
+## Basic usage
+
+```python
+from vella import govern
+
+result = govern(
+    intent="EXECUTE_CHANGE",
+    evidence_mask=1,
+)
+
+print(result["decision"])    # ALLOWED | DENIED
+print(result["reason_code"]) # reason code string
+```
+
+## With proof bundle
+
+```python
+from vella import govern
+
+signing_key = open("./proof-signing.pem", "r", encoding="utf-8").read()
+
+result = govern(
+    intent="EXECUTE_CHANGE",
+    evidence_mask=1,
+    proof_signing_key=signing_key,
+)
+
+print(result["proof_bundle"]["kind"])  # vella_proof_bundle_v1
+```
+
+## When to use this SDK
+
+This SDK runs VELLA in-process inside your Python application. It is the right choice for agent tool-call hooks, CI/CD gating, edge compute, research notebooks, batch processing, and any context where microsecond-latency adjudication is needed without a separate service.
+
+For enterprise service mesh, polyglot environments (Go, Java, .NET), Kubernetes admission control, or multi-tenant deployments, a different VELLA component (the runtime service or sidecar adapter) is the better fit. See the full [deployment scope](../../DEPLOYMENT.md) in the repository root.
+
+## API
+
+- `govern(intent, evidence_mask, authority_scope=None, policy_version=None, proof_signing_key=None)`
+  - Returns a dict with `decision`, `reason_code`, `latency_us`, and optional `proof_bundle`/`proof_error`
+
+## Reference docs
+
+See the root repository docs for full protocol details:
+- `spec/icd.md`
+- `spec/schemas/proof.json`
+- `verify/`

vella_sdk-1.0.1/README.md

@@ -0,0 +1,69 @@
+# vella-sdk
+
+Python SDK for deterministic pre-execution adjudication and signed proof-bundle generation.
+
+## Install
+
+```bash
+pip install vella-sdk
+```
+
+## From source (development)
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy --strict vella/
+```
+
+## Basic usage
+
+```python
+from vella import govern
+
+result = govern(
+    intent="EXECUTE_CHANGE",
+    evidence_mask=1,
+)
+
+print(result["decision"])    # ALLOWED | DENIED
+print(result["reason_code"]) # reason code string
+```
+
+## With proof bundle
+
+```python
+from vella import govern
+
+signing_key = open("./proof-signing.pem", "r", encoding="utf-8").read()
+
+result = govern(
+    intent="EXECUTE_CHANGE",
+    evidence_mask=1,
+    proof_signing_key=signing_key,
+)
+
+print(result["proof_bundle"]["kind"])  # vella_proof_bundle_v1
+```
+
+## When to use this SDK
+
+This SDK runs VELLA in-process inside your Python application. It is the right choice for agent tool-call hooks, CI/CD gating, edge compute, research notebooks, batch processing, and any context where microsecond-latency adjudication is needed without a separate service.
+
+For enterprise service mesh, polyglot environments (Go, Java, .NET), Kubernetes admission control, or multi-tenant deployments, a different VELLA component (the runtime service or sidecar adapter) is the better fit. See the full [deployment scope](../../DEPLOYMENT.md) in the repository root.
+
+## API
+
+- `govern(intent, evidence_mask, authority_scope=None, policy_version=None, proof_signing_key=None)`
+  - Returns a dict with `decision`, `reason_code`, `latency_us`, and optional `proof_bundle`/`proof_error`
+
+## Reference docs
+
+See the root repository docs for full protocol details:
+- `spec/icd.md`
+- `spec/schemas/proof.json`
+- `verify/`

vella_sdk-1.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vella-sdk"
+version = "1.0.1"
+description = "VELLA — deterministic pre-execution governance substrate. SDK for producing signed decision records."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "Vella Cognitive, LLC", email = "agent@vellacognitive.com" }
+]
+dependencies = [
+  "cryptography>=41.0"
+]
+keywords = [
+  "vella",
+  "governance",
+  "ai-safety",
+  "pre-execution",
+  "policy",
+  "audit",
+  "proof-bundle"
+]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Security",
+  "Topic :: Software Development :: Libraries :: Python Modules"
+]
+
+[project.optional-dependencies]
+dev = ["ruff", "mypy", "pytest"]
+
+[project.urls]
+Homepage = "https://vellacognitive.com/research/an-inspectable-substrate-for-ai-governance"
+Repository = "https://github.com/vellacognitive/vella-substrate"
+Issues = "https://github.com/vellacognitive/vella-substrate/issues"
+
+[tool.setuptools.packages.find]
+include = ["vella*"]
+
+[tool.mypy]
+strict = true

vella_sdk-1.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

vella_sdk-1.0.1/tests/test_evaluator.py

@@ -0,0 +1,61 @@
+from vella import govern
+
+
+def test_execute_change_with_authn_is_allowed() -> None:
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1)
+    assert result["decision"] == "ALLOWED"
+    assert result["reason_code"] == "POLICY_SATISFIED"
+
+
+def test_execute_change_without_evidence_is_denied() -> None:
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=0)
+    assert result["decision"] == "DENIED"
+    assert result["reason_code"] == "E_EVIDENCE_MISSING"
+
+
+def test_escalate_with_authn_authz_is_allowed() -> None:
+    result = govern(intent="ESCALATE_PRIVILEGE", evidence_mask=3)
+    assert result["decision"] == "ALLOWED"
+    assert result["reason_code"] == "POLICY_SATISFIED"
+
+
+def test_escalate_with_only_authn_is_denied() -> None:
+    result = govern(intent="ESCALATE_PRIVILEGE", evidence_mask=1)
+    assert result["decision"] == "DENIED"
+    assert result["reason_code"] == "E_EVIDENCE_MISSING"
+
+
+def test_data_export_with_authn_authz_is_allowed() -> None:
+    result = govern(intent="DATA_EXPORT", evidence_mask=3)
+    assert result["decision"] == "ALLOWED"
+    assert result["reason_code"] == "POLICY_SATISFIED"
+
+
+def test_unknown_intent_is_denied_fast() -> None:
+    result = govern(intent="UNKNOWN_INTENT", evidence_mask=15)
+    assert result["decision"] == "DENIED"
+    assert result["reason_code"] == "DENY_FAST"
+
+
+def test_missing_intent_is_denied() -> None:
+    result = govern(intent="", evidence_mask=1)
+    assert result["decision"] == "DENIED"
+    assert result["reason_code"] == "E_INTENT_REQUIRED"
+
+
+def test_policy_version_mismatch_is_denied() -> None:
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1, policy_version="v99")
+    assert result["decision"] == "DENIED"
+    assert result["reason_code"] == "E_POLICY_VERSION_MISMATCH"
+
+
+def test_unknown_authority_scope_is_denied_fast() -> None:
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1, authority_scope="unknown")
+    assert result["decision"] == "DENIED"
+    assert result["reason_code"] == "DENY_FAST"
+
+
+def test_symbolic_evidence_list_is_supported() -> None:
+    result = govern(intent="DATA_EXPORT", evidence_mask=["AUTHN", "AUTHZ"])
+    assert result["decision"] == "ALLOWED"
+    assert result["reason_code"] == "POLICY_SATISFIED"

vella_sdk-1.0.1/tests/test_proof.py

@@ -0,0 +1,90 @@
+import base64
+import hashlib
+import json
+from pathlib import Path
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature
+
+from vella import govern
+
+SIGNING_EXCLUDED = {
+    "envelope_hash",
+    "signature_alg",
+    "signature",
+    "sha256_bundle",
+    "key_id",
+    "kind",
+    "exported_at",
+}
+
+
+def _read_fixture(name: str) -> str:
+    return (Path(__file__).parent / "fixtures" / name).read_text(encoding="utf-8")
+
+
+def test_proof_bundle_is_generated() -> None:
+    private_key = _read_fixture("test-signing-private.pem")
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1, proof_signing_key=private_key)
+    proof_bundle = result.get("proof_bundle")
+    assert isinstance(proof_bundle, dict)
+    assert proof_bundle["kind"] == "vella_proof_bundle_v1"
+
+
+def test_envelope_hash_verifies() -> None:
+    private_key = _read_fixture("test-signing-private.pem")
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1, proof_signing_key=private_key)
+    proof_bundle = result["proof_bundle"]
+    assert isinstance(proof_bundle, dict)
+
+    envelope = {k: v for k, v in proof_bundle.items() if k not in SIGNING_EXCLUDED}
+    canonical_envelope = json.dumps(envelope, sort_keys=True, separators=(",", ":"))
+    expected_hash = f"sha256:{hashlib.sha256(canonical_envelope.encode('utf-8')).hexdigest()}"
+    assert proof_bundle["envelope_hash"] == expected_hash
+
+
+def test_signature_verifies() -> None:
+    private_key = _read_fixture("test-signing-private.pem")
+    public_key_pem = _read_fixture("test-signing-public.pem")
+
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1, proof_signing_key=private_key)
+    proof_bundle = result["proof_bundle"]
+    assert isinstance(proof_bundle, dict)
+
+    public_key = serialization.load_pem_public_key(public_key_pem.encode("utf-8"))
+    assert isinstance(public_key, ec.EllipticCurvePublicKey)
+
+    signature_bytes = base64.b64decode(str(proof_bundle["signature"]))
+    r_value = int.from_bytes(signature_bytes[:32], "big")
+    s_value = int.from_bytes(signature_bytes[32:], "big")
+    der_signature = encode_dss_signature(r_value, s_value)
+
+    public_key.verify(
+        der_signature,
+        str(proof_bundle["envelope_hash"]).encode("utf-8"),
+        ec.ECDSA(hashes.SHA256()),
+    )
+
+
+def test_bundle_hash_verifies() -> None:
+    private_key = _read_fixture("test-signing-private.pem")
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1, proof_signing_key=private_key)
+    proof_bundle = result["proof_bundle"]
+    assert isinstance(proof_bundle, dict)
+
+    envelope = {k: v for k, v in proof_bundle.items() if k not in SIGNING_EXCLUDED}
+    bundle_for_hash = {
+        **envelope,
+        "envelope_hash": proof_bundle["envelope_hash"],
+        "signature_alg": proof_bundle["signature_alg"],
+        "signature": proof_bundle["signature"],
+    }
+    canonical_bundle = json.dumps(bundle_for_hash, sort_keys=True, separators=(",", ":"))
+    expected_hash = f"sha256:{hashlib.sha256(canonical_bundle.encode('utf-8')).hexdigest()}"
+    assert proof_bundle["sha256_bundle"] == expected_hash
+
+
+def test_proof_bundle_absent_when_no_signing_key() -> None:
+    result = govern(intent="EXECUTE_CHANGE", evidence_mask=1)
+    assert "proof_bundle" not in result

vella_sdk-1.0.1/vella/__init__.py

@@ -0,0 +1,70 @@
+"""VELLA SDK — MIT License — Copyright (c) 2026 Vella Cognitive, LLC"""
+
+from __future__ import annotations
+
+import time
+
+from .evaluator import create_evaluator
+from .policy import DEFAULT_POLICY
+from .proof import build_envelope, sign_bundle
+
+__version__ = "1.0.1"
+
+_EVALUATOR = create_evaluator(DEFAULT_POLICY)
+
+
+def govern(
+    intent: str | None,
+    evidence_mask: object,
+    authority_scope: str | None = None,
+    policy_version: str | None = None,
+    proof_signing_key: str | bytes | None = None,
+) -> dict[str, object]:
+    start = time.monotonic_ns()
+
+    try:
+        result = _EVALUATOR.evaluate(
+            {
+                "intent_id": intent,
+                "evidence_mask": evidence_mask,
+                "authority_scope_id": authority_scope,
+                "policy_version": policy_version,
+            }
+        )
+        latency_us = (time.monotonic_ns() - start) // 1000
+        output: dict[str, object] = {
+            "decision": result["decision"],
+            "reason_code": result["reason_code"],
+            "latency_us": latency_us,
+        }
+
+        if proof_signing_key is not None:
+            try:
+                envelope = build_envelope(
+                    {
+                        "intent_id": intent,
+                        "evidence_mask": evidence_mask,
+                        "authority_scope_id": authority_scope,
+                        "policy_version": policy_version,
+                    },
+                    result,
+                    {
+                        "policyVersion": _EVALUATOR.policy_version,
+                        "authorityScope": authority_scope,
+                    },
+                )
+                output["proof_bundle"] = sign_bundle(envelope, proof_signing_key)
+            except Exception as proof_error:  # noqa: BLE001
+                output["proof_bundle"] = None
+                output["proof_error"] = str(proof_error)
+
+        return output
+    except Exception:  # noqa: BLE001
+        return {
+            "decision": "DENIED",
+            "reason_code": "E_EVALUATOR_INTERNAL",
+            "latency_us": 0,
+        }
+
+
+__all__ = ["govern", "DEFAULT_POLICY", "__version__"]

vella_sdk-1.0.1/vella/evaluator.py

@@ -0,0 +1,211 @@
+"""VELLA SDK — MIT License — Copyright (c) 2026 Vella Cognitive, LLC"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Mapping
+
+from .policy import DEFAULT_POLICY
+
+Decision = dict[str, str]
+
+DECISION_ALLOWED: Decision = {"decision": "ALLOWED", "reason_code": "POLICY_SATISFIED"}
+DECISION_DENIED_FAST: Decision = {"decision": "DENIED", "reason_code": "DENY_FAST"}
+DECISION_DENIED_INTENT_REQUIRED: Decision = {
+    "decision": "DENIED",
+    "reason_code": "E_INTENT_REQUIRED",
+}
+DECISION_DENIED_POLICY_VERSION: Decision = {
+    "decision": "DENIED",
+    "reason_code": "E_POLICY_VERSION_MISMATCH",
+}
+DECISION_DENIED_EVIDENCE: Decision = {
+    "decision": "DENIED",
+    "reason_code": "E_EVIDENCE_MISSING",
+}
+
+
+@dataclass(frozen=True)
+class CompiledScope:
+    allow_unknown_intents: bool
+    default_required_mask: int
+    intent_rules: dict[str, int]
+
+
+@dataclass(frozen=True)
+class CompiledPolicy:
+    policy_version: str
+    default_scope: str
+    evidence_bits: dict[str, int]
+    scopes: dict[str, CompiledScope]
+
+
+def _normalize_id(value: object | None) -> str:
+    if value is None:
+        return ""
+    return str(value).strip().upper()
+
+
+def _parse_unsigned_int_strict(text: str) -> int:
+    if len(text) == 0:
+        return -1
+    value = 0
+    for ch in text:
+        code = ord(ch)
+        if code < 48 or code > 57:
+            return -1
+        value = (value * 10) + (code - 48)
+        if not math.isfinite(value):
+            return -1
+    return value & 0xFFFFFFFF
+
+
+def to_evidence_mask(value: object, evidence_bits: Mapping[str, int]) -> int:
+    if isinstance(value, bool):
+        return 0
+
+    if isinstance(value, int):
+        return value & 0xFFFFFFFF
+
+    if isinstance(value, float) and math.isfinite(value):
+        return int(value) & 0xFFFFFFFF
+
+    if isinstance(value, str):
+        trimmed = value.strip()
+        numeric = _parse_unsigned_int_strict(trimmed)
+        if numeric >= 0:
+            return numeric & 0xFFFFFFFF
+        bit = evidence_bits.get(_normalize_id(trimmed))
+        return (bit & 0xFFFFFFFF) if bit is not None else 0
+
+    if isinstance(value, list):
+        mask = 0
+        for item in value:
+            bit = evidence_bits.get(_normalize_id(item))
+            if bit is not None:
+                mask |= bit
+        return mask & 0xFFFFFFFF
+
+    return 0
+
+
+def _to_int(value: object, default: int = 0) -> int:
+    if isinstance(value, bool):
+        return default
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float) and math.isfinite(value):
+        return int(value)
+    if isinstance(value, str):
+        parsed = _parse_unsigned_int_strict(value.strip())
+        if parsed >= 0:
+            return parsed
+    return default
+
+
+def compile_policy(policy_input: Mapping[str, object] | None = None) -> CompiledPolicy:
+    policy = policy_input if policy_input is not None else DEFAULT_POLICY
+
+    raw_evidence = policy.get("evidenceBits")
+    evidence_bits: dict[str, int] = {}
+    if isinstance(raw_evidence, Mapping):
+        for key, value in raw_evidence.items():
+            if not isinstance(key, str):
+                continue
+            evidence_bits[key] = _to_int(value) & 0xFFFFFFFF
+
+    raw_scopes = policy.get("scopes")
+    scopes: dict[str, CompiledScope] = {}
+    if isinstance(raw_scopes, Mapping):
+        for scope_name_obj, scope_cfg_obj in raw_scopes.items():
+            if not isinstance(scope_name_obj, str):
+                continue
+            scope_name = scope_name_obj
+            scope_cfg = scope_cfg_obj if isinstance(scope_cfg_obj, Mapping) else {}
+
+            raw_intents = scope_cfg.get("intents")
+            intent_rules: dict[str, int] = {}
+            if isinstance(raw_intents, Mapping):
+                for intent_name_obj, intent_mask_obj in raw_intents.items():
+                    if not isinstance(intent_name_obj, str):
+                        continue
+                    intent_name = _normalize_id(intent_name_obj)
+                    if not intent_name:
+                        continue
+                    intent_rules[intent_name] = _to_int(intent_mask_obj) & 0xFFFFFFFF
+
+            allow_unknown = bool(scope_cfg.get("allowUnknownIntents") is True)
+            default_required = _to_int(scope_cfg.get("defaultRequiredMask"), 0) & 0xFFFFFFFF
+            scopes[scope_name] = CompiledScope(
+                allow_unknown_intents=allow_unknown,
+                default_required_mask=default_required,
+                intent_rules=intent_rules,
+            )
+
+    default_scope_obj = policy.get("defaultScope")
+    default_scope = str(default_scope_obj) if default_scope_obj is not None else "sdk_v1_default"
+
+    policy_version_obj = policy.get("policyVersion")
+    policy_version = str(policy_version_obj) if policy_version_obj is not None else "min-v1"
+
+    return CompiledPolicy(
+        policy_version=policy_version,
+        default_scope=default_scope,
+        evidence_bits=evidence_bits,
+        scopes=scopes,
+    )
+
+
+class Evaluator:
+    def __init__(self, compiled_policy: CompiledPolicy) -> None:
+        self._compiled = compiled_policy
+        self._default_scope = compiled_policy.scopes.get(compiled_policy.default_scope)
+        self.policy_version = compiled_policy.policy_version
+
+    def evaluate(self, input_dict: Mapping[str, object] | None) -> Decision:
+        if input_dict is None:
+            return DECISION_DENIED_INTENT_REQUIRED
+
+        raw_intent = (
+            input_dict.get("intent_id")
+            or input_dict.get("intent")
+            or input_dict.get("action")
+        )
+        intent_id = _normalize_id(raw_intent)
+        if not intent_id:
+            return DECISION_DENIED_INTENT_REQUIRED
+
+        authority_scope_id = input_dict.get("authority_scope_id")
+        if authority_scope_id is None or authority_scope_id == "":
+            scope = self._default_scope
+            if scope is None:
+                return DECISION_DENIED_FAST
+        else:
+            scope = self._compiled.scopes.get(str(authority_scope_id))
+            if scope is None:
+                return DECISION_DENIED_FAST
+
+        required_mask = scope.intent_rules.get(intent_id)
+        if required_mask is None:
+            if not scope.allow_unknown_intents:
+                return DECISION_DENIED_FAST
+            required_mask = scope.default_required_mask
+
+        requested_policy_version = input_dict.get("policy_version")
+        if (
+            requested_policy_version is not None
+            and requested_policy_version != ""
+            and str(requested_policy_version) != self._compiled.policy_version
+        ):
+            return DECISION_DENIED_POLICY_VERSION
+
+        evidence_mask = to_evidence_mask(input_dict.get("evidence_mask"), self._compiled.evidence_bits)
+        if (evidence_mask & required_mask) != required_mask:
+            return DECISION_DENIED_EVIDENCE
+
+        return DECISION_ALLOWED
+
+
+def create_evaluator(policy_input: Mapping[str, object] | None = None) -> Evaluator:
+    return Evaluator(compile_policy(policy_input))

vella_sdk-1.0.1/vella/policy.py

@@ -0,0 +1,27 @@
+"""VELLA SDK — MIT License — Copyright (c) 2026 Vella Cognitive, LLC"""
+
+from __future__ import annotations
+
+from typing import Final
+
+DEFAULT_POLICY: Final[dict[str, object]] = {
+    "policyVersion": "min-v1",
+    "defaultScope": "sdk_v1_default",
+    "evidenceBits": {
+        "AUTHN": 1,
+        "AUTHZ": 2,
+        "FRESHNESS": 4,
+        "ATTESTATION": 8,
+    },
+    "scopes": {
+        "sdk_v1_default": {
+            "allowUnknownIntents": False,
+            "defaultRequiredMask": 1,
+            "intents": {
+                "EXECUTE_CHANGE": 1,
+                "ESCALATE_PRIVILEGE": 1 | 2,
+                "DATA_EXPORT": 1 | 2,
+            },
+        },
+    },
+}

vella_sdk-1.0.1/vella/proof.py

@@ -0,0 +1,99 @@
+"""VELLA SDK — MIT License — Copyright (c) 2026 Vella Cognitive, LLC"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import os
+import struct
+import time
+from datetime import datetime, timezone
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric import utils as asym_utils
+
+
+def _uuidv7() -> str:
+    buffer = bytearray(os.urandom(16))
+    now_ms = int(time.time() * 1000)
+    timestamp_bytes = struct.pack(">Q", now_ms)
+    buffer[0:6] = timestamp_bytes[2:8]
+    buffer[6] = (buffer[6] & 0x0F) | 0x70
+    buffer[8] = (buffer[8] & 0x3F) | 0x80
+    hexed = buffer.hex()
+    return f"{hexed[:8]}-{hexed[8:12]}-{hexed[12:16]}-{hexed[16:20]}-{hexed[20:]}"
+
+
+def _load_ec_private_key(signing_key_pem: str | bytes) -> ec.EllipticCurvePrivateKey:
+    key_bytes = signing_key_pem.encode("utf-8") if isinstance(signing_key_pem, str) else signing_key_pem
+    private_key = serialization.load_pem_private_key(key_bytes, password=None)
+    if not isinstance(private_key, ec.EllipticCurvePrivateKey):
+        raise ValueError("signing key must be an EC private key")
+    return private_key
+
+
+def build_envelope(
+    intent_input: dict[str, object] | None,
+    decision_result: dict[str, str] | None,
+    context: dict[str, object] | None,
+) -> dict[str, object]:
+    request = intent_input if isinstance(intent_input, dict) else {}
+    decision = decision_result if isinstance(decision_result, dict) else {}
+    ctx = context if isinstance(context, dict) else {}
+
+    return {
+        "envelope_id": f"env_{_uuidv7()}",
+        "intent": request.get("intent_id") or request.get("intent") or request.get("action"),
+        "proposed": request.get("proposed"),
+        "authority_scope": ctx.get("authorityScope") or request.get("authority_scope_id") or "sdk_v1_default",
+        "evidence_mask": request.get("evidence_mask", 0),
+        "decision": decision.get("decision", "DENIED"),
+        "reason_code": decision.get("reason_code", "E_EVALUATOR_INTERNAL"),
+        "policy_version": ctx.get("policyVersion", "min-v1"),
+        "build_hash": ctx.get("buildHash", "unset"),
+        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "ok": decision.get("decision") in ("ALLOWED", "DENIED"),
+        "external_effects": False,
+    }
+
+
+def derive_key_id(signing_key_pem: str | bytes) -> str:
+    private_key = _load_ec_private_key(signing_key_pem)
+    public_der = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    return f"key_{hashlib.sha256(public_der).hexdigest()[:16]}"
+
+
+def sign_bundle(envelope: dict[str, object], signing_key_pem: str | bytes) -> dict[str, object]:
+    canonical_envelope = json.dumps(envelope, sort_keys=True, separators=(",", ":"))
+    envelope_hash = f"sha256:{hashlib.sha256(canonical_envelope.encode('utf-8')).hexdigest()}"
+
+    private_key = _load_ec_private_key(signing_key_pem)
+    der_signature = private_key.sign(envelope_hash.encode("utf-8"), ec.ECDSA(hashes.SHA256()))
+    r_value, s_value = asym_utils.decode_dss_signature(der_signature)
+    signature_bytes = r_value.to_bytes(32, "big") + s_value.to_bytes(32, "big")
+    signature = base64.b64encode(signature_bytes).decode("utf-8")
+
+    bundle_for_hash = {
+        **envelope,
+        "envelope_hash": envelope_hash,
+        "signature_alg": "ecdsa-p256-sha256",
+        "signature": signature,
+    }
+    canonical_bundle = json.dumps(bundle_for_hash, sort_keys=True, separators=(",", ":"))
+    sha256_bundle = f"sha256:{hashlib.sha256(canonical_bundle.encode('utf-8')).hexdigest()}"
+
+    return {
+        **envelope,
+        "envelope_hash": envelope_hash,
+        "signature_alg": "ecdsa-p256-sha256",
+        "signature": signature,
+        "sha256_bundle": sha256_bundle,
+        "key_id": derive_key_id(signing_key_pem),
+        "kind": "vella_proof_bundle_v1",
+        "exported_at": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }

vella_sdk-1.0.1/vella_sdk.egg-info/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: vella-sdk
+Version: 1.0.1
+Summary: VELLA — deterministic pre-execution governance substrate. SDK for producing signed decision records.
+Author-email: "Vella Cognitive, LLC" <agent@vellacognitive.com>
+License: MIT
+Project-URL: Homepage, https://vellacognitive.com/research/an-inspectable-substrate-for-ai-governance
+Project-URL: Repository, https://github.com/vellacognitive/vella-substrate
+Project-URL: Issues, https://github.com/vellacognitive/vella-substrate/issues
+Keywords: vella,governance,ai-safety,pre-execution,policy,audit,proof-bundle
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+
+# vella-sdk
+
+Python SDK for deterministic pre-execution adjudication and signed proof-bundle generation.
+
+## Install
+
+```bash
+pip install vella-sdk
+```
+
+## From source (development)
+
+```bash
+python3 -m venv .venv
+. .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy --strict vella/
+```
+
+## Basic usage
+
+```python
+from vella import govern
+
+result = govern(
+    intent="EXECUTE_CHANGE",
+    evidence_mask=1,
+)
+
+print(result["decision"])    # ALLOWED | DENIED
+print(result["reason_code"]) # reason code string
+```
+
+## With proof bundle
+
+```python
+from vella import govern
+
+signing_key = open("./proof-signing.pem", "r", encoding="utf-8").read()
+
+result = govern(
+    intent="EXECUTE_CHANGE",
+    evidence_mask=1,
+    proof_signing_key=signing_key,
+)
+
+print(result["proof_bundle"]["kind"])  # vella_proof_bundle_v1
+```
+
+## When to use this SDK
+
+This SDK runs VELLA in-process inside your Python application. It is the right choice for agent tool-call hooks, CI/CD gating, edge compute, research notebooks, batch processing, and any context where microsecond-latency adjudication is needed without a separate service.
+
+For enterprise service mesh, polyglot environments (Go, Java, .NET), Kubernetes admission control, or multi-tenant deployments, a different VELLA component (the runtime service or sidecar adapter) is the better fit. See the full [deployment scope](../../DEPLOYMENT.md) in the repository root.
+
+## API
+
+- `govern(intent, evidence_mask, authority_scope=None, policy_version=None, proof_signing_key=None)`
+  - Returns a dict with `decision`, `reason_code`, `latency_us`, and optional `proof_bundle`/`proof_error`
+
+## Reference docs
+
+See the root repository docs for full protocol details:
+- `spec/icd.md`
+- `spec/schemas/proof.json`
+- `verify/`

vella_sdk-1.0.1/vella_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+tests/test_evaluator.py
+tests/test_proof.py
+vella/__init__.py
+vella/evaluator.py
+vella/policy.py
+vella/proof.py
+vella_sdk.egg-info/PKG-INFO
+vella_sdk.egg-info/SOURCES.txt
+vella_sdk.egg-info/dependency_links.txt
+vella_sdk.egg-info/requires.txt
+vella_sdk.egg-info/top_level.txt

vella_sdk-1.0.1/vella_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

vella_sdk-1.0.1/vella_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+cryptography>=41.0
+
+[dev]
+ruff
+mypy
+pytest

vella_sdk-1.0.1/vella_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+vella