openverify 0.1.0__py3-none-any.whl

openverify/__init__.py

@@ -0,0 +1,38 @@
+"""Draft domain-neutral verification protocol implementation."""
+
+__version__ = "0.1.0"
+
+from openverify.authoring import Graph
+from openverify.dataflow import validate_run_inputs
+from openverify.errors import ProtocolError
+from openverify.fingerprint import fingerprint
+from openverify.inspection import flattened_status, inspect_definition
+from openverify.relay import Relay
+from openverify.serialization import serialize
+from openverify.validation import (
+    load_schema,
+    parse_definition,
+    parse_result,
+    parse_run_record,
+    validate_definition,
+    validate_executable_definition,
+    validate_result,
+)
+
+__all__ = [
+    "Graph",
+    "Relay",
+    "ProtocolError",
+    "fingerprint",
+    "flattened_status",
+    "inspect_definition",
+    "load_schema",
+    "parse_definition",
+    "parse_result",
+    "parse_run_record",
+    "serialize",
+    "validate_definition",
+    "validate_executable_definition",
+    "validate_result",
+    "validate_run_inputs",
+]

openverify/adapters/__init__.py

@@ -0,0 +1,28 @@
+"""Trusted local implementations bound to exact capability ID/version requirements."""
+
+from typing import Protocol
+
+from openverify.model import Context, Decision, ExecutionObservation, Result
+
+
+class Adapter(Protocol):
+    def execute(
+        self, inputs: Context, config: Context, /
+    ) -> ExecutionObservation | Context | Result | Decision: ...
+
+
+class Registry:
+    def __init__(self) -> None:
+        self.operations: dict[tuple[str, str], Adapter] = {}
+
+    def register(self, capability_id: str, capability_version: str, adapter: Adapter) -> None:
+        self.operations[(capability_id, capability_version)] = adapter
+
+    def register_derive(self, name: str, adapter: Adapter, *, version: str = "1") -> None:
+        self.register(name, version, adapter)
+
+    def register_evaluate(self, name: str, adapter: Adapter, *, version: str = "1") -> None:
+        self.register(name, version, adapter)
+
+    def register_control(self, name: str, adapter: Adapter, *, version: str = "1") -> None:
+        self.register(name, version, adapter)

openverify/adapters/demo.py

@@ -0,0 +1,102 @@
+"""Small local examples, not protocol primitives or an untrusted code runner."""
+
+import re
+from typing import cast
+
+from openverify.adapters import Registry
+from openverify.errors import ProtocolError
+from openverify.model import Context, Decision, Evidence, Result
+from openverify.validation import parse_result
+
+
+def known(verdict: str | None = None, score: float | None = None) -> Result:
+    return parse_result(
+        {
+            "protocol": "draft",
+            "disposition": "EXECUTED",
+            "execution_outcome": "SUCCESS",
+            "applicability": "APPLICABLE",
+            "determination": "KNOWN",
+            "verdict": verdict,
+            "score": score,
+        }
+    )
+
+
+class ConstantEvaluator:
+    version = "1"
+
+    def execute(self, inputs: Context, config: Context) -> Result:
+        return parse_result(config["result"])
+
+
+class RegexEvaluator:
+    version = "1"
+
+    def execute(self, inputs: Context, config: Context) -> Result:
+        text = inputs[cast(str, config["key"])]
+        pattern = config["pattern"]
+        must_match = config["must_match"]
+        if (
+            not isinstance(text, str)
+            or not isinstance(pattern, str)
+            or type(must_match) is not bool
+        ):
+            raise ProtocolError(
+                "EXECUTOR_ERROR", "Regex demo needs text, pattern, and boolean must_match"
+            )
+        matched = re.search(pattern, text) is not None
+        result = known("PASS" if matched == must_match else "FAIL")
+        return result.model_copy(
+            update={"evidence": [Evidence(message=f"Pattern matched: {matched}")]}
+        )
+
+
+class RangeEvaluator:
+    version = "1"
+
+    def execute(self, inputs: Context, config: Context) -> Result:
+        value = inputs[cast(str, config["key"])]
+        low, high = config["minimum"], config["maximum"]
+        if any(type(v) not in (int, float) for v in (value, low, high)):
+            raise ProtocolError("EXECUTOR_ERROR", "Range demo requires numeric values")
+        if cast(float, low) > cast(float, high):
+            raise ProtocolError("EXECUTOR_ERROR", "Inverted range")
+        return known(
+            "PASS" if cast(float, low) <= cast(float, value) <= cast(float, high) else "FAIL"
+        )
+
+
+class LengthDeriver:
+    version = "1"
+
+    def execute(self, inputs: Context, config: Context) -> Context:
+        value = inputs[cast(str, config["key"])]
+        if not isinstance(value, str):
+            raise ProtocolError("EXECUTOR_ERROR", "Length demo requires text")
+        return {cast(str, config["output_key"]): len(value)}
+
+
+class UnknownRouter:
+    version = "1"
+
+    def execute(self, inputs: Context, config: Context) -> Decision:
+        if any(
+            isinstance(r, dict) and r.get("determination") == "UNKNOWN" for r in inputs.values()
+        ):
+            return Decision(
+                kind="ROUTE",
+                destination=cast(str, config["destination"]),
+                reason="Uncertain evaluation",
+            )
+        return Decision(kind="CONTINUE")
+
+
+def demo_registry() -> Registry:
+    registry = Registry()
+    registry.register_evaluate("com.example.demo.constant", ConstantEvaluator())
+    registry.register_evaluate("com.example.demo.regex", RegexEvaluator())
+    registry.register_evaluate("com.example.demo.range", RangeEvaluator())
+    registry.register_derive("com.example.demo.length", LengthDeriver())
+    registry.register_control("com.example.demo.unknown_route", UnknownRouter())
+    return registry

openverify/authoring/__init__.py

@@ -0,0 +1,6 @@
+"""Portable VCP graph authoring."""
+
+from .graph import Graph, NodeRef
+from .references import Ref, constant, external
+
+__all__ = ("Graph", "NodeRef", "Ref", "constant", "external")

openverify/authoring/graph.py

@@ -0,0 +1,262 @@
+"""An explicit, small VCP builder. build() always returns a validated SDK definition."""
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Literal, TypedDict, Unpack, cast
+
+from pydantic import JsonValue
+
+from openverify.authoring.references import Ref, constant
+from openverify.inspection import inspect_definition
+from openverify.model import (
+    AdmissionPolicy,
+    ArtifactRef,
+    Capability,
+    Constant,
+    Context,
+    Criterion,
+    Edge,
+    ExecutionPolicy,
+    Guard,
+    InputPort,
+    JsonSchema,
+    Node,
+    OperationRequirement,
+    OutputPort,
+    ResourceVector,
+    RunInput,
+    UpstreamOutput,
+    VerificationDefinition,
+)
+from openverify.model import (
+    Graph as VCPGraph,
+)
+from openverify.serialization import serialize, to_data
+from openverify.validation import HANDLING, parse_definition
+
+type NodeKind = Literal["DERIVE", "EVALUATE", "CONTROL", "AGGREGATE"]
+
+
+@dataclass(frozen=True)
+class NodeRef:
+    id: str
+    outputs: dict[str, Ref]
+
+    def __getitem__(self, name: str) -> Ref:
+        return self.outputs[name]
+
+    @property
+    def result(self) -> Ref:
+        return self["result"]
+
+    @property
+    def decision(self) -> Ref:
+        return self["decision"]
+
+
+class NodeOptions(TypedDict, total=False):
+    version: str
+    inputs: dict[str, Ref] | None
+    outputs: dict[str, JsonSchema] | None
+    config: Context | None
+    config_schema: JsonSchema | None
+    dependencies: list[NodeRef] | None
+    input_ports: list[InputPort] | None
+    aggregate_inputs: list[str] | None
+    resource_estimate: ResourceVector | None
+
+
+class Graph:
+    def __init__(
+        self,
+        id: str,
+        *,
+        version: str = "1",
+        subject: ArtifactRef | None = None,
+        criterion: Criterion | None = None,
+        judgment_schema: JsonSchema = True,
+        execution_policy: ExecutionPolicy | None = None,
+    ) -> None:
+        self.id = id
+        self.version = version
+        self.subject = subject or ArtifactRef(id=id, type="declared-input", locator={"graph": id})
+        self.criterion = criterion or Criterion(id=id, description=f"Verification defined by {id}")
+        self.judgment_schema = judgment_schema
+        self.execution_policy = execution_policy or ExecutionPolicy(
+            activation=Capability(executor_ref="MANUAL"),
+            selection=Capability(executor_ref="EXPLICIT"),
+            admission=AdmissionPolicy(strategy="ALWAYS"),
+        )
+        self._inputs: list[InputPort] = []
+        self._nodes: list[Node] = []
+        self._edges: list[Edge] = []
+
+    def input(
+        self,
+        name: str,
+        schema: JsonSchema,
+        *,
+        required: bool = True,
+        default: Constant | None = None,
+    ) -> Ref:
+        self._inputs.append(
+            InputPort(
+                name=name,
+                schema=deepcopy(schema),
+                required=required,
+                on_unavailable="BLOCK" if required else "DEFAULT" if default else "OMIT",
+                default=default,
+            )
+        )
+        return Ref(RunInput(name=name), deepcopy(schema))
+
+    def node(
+        self,
+        id: str,
+        kind: NodeKind,
+        capability: str,
+        *,
+        version: str = "1",
+        inputs: dict[str, Ref] | None = None,
+        outputs: dict[str, JsonSchema] | None = None,
+        config: Context | None = None,
+        config_schema: JsonSchema | None = None,
+        dependencies: list[NodeRef] | None = None,
+        input_ports: list[InputPort] | None = None,
+        aggregate_inputs: list[str] | None = None,
+        resource_estimate: ResourceVector | None = None,
+    ) -> NodeRef:
+        bindings = dict(inputs or {})
+        if kind in ("EVALUATE", "AGGREGATE"):
+            if "subject" in bindings or "criterion" in bindings:
+                raise ValueError(
+                    "Builder binds definition subject and criterion; "
+                    "use raw VCP for explicit declarations"
+                )
+            bindings.update(
+                subject=constant(to_data(self.subject), {"type": "object"}),
+                criterion=constant(to_data(self.criterion), {"type": "object"}),
+            )
+        ports = {p.name: p for p in input_ports or []}
+        for name, ref in bindings.items():
+            if name not in ports:
+                ports[name] = InputPort(
+                    name=name, schema=deepcopy(ref.schema), required=True, on_unavailable="BLOCK"
+                )
+        declared = [
+            OutputPort(name=name, schema=deepcopy(schema), role="INFORMATION")
+            for name, schema in (outputs or {}).items()
+        ]
+        if kind in ("EVALUATE", "AGGREGATE", "CONTROL"):
+            role = "DECISION" if kind == "CONTROL" else "RESULT"
+            declared.append(OutputPort(name=role.lower(), schema={"type": "object"}, role=role))
+        self._nodes.append(
+            Node(
+                id=id,
+                kind=kind,
+                operation=OperationRequirement(
+                    capability_id=capability, capability_version=version
+                ),
+                inputs=list(ports.values()),
+                outputs=declared,
+                bindings={n: deepcopy(r.source) for n, r in bindings.items()},
+                aggregate_inputs=aggregate_inputs or [],
+                config=deepcopy(config or {}),
+                config_schema=deepcopy(config_schema),
+                resource_estimate=deepcopy(resource_estimate or {}),
+            )
+        )
+        predecessors = [
+            r.source.node_id for r in bindings.values() if isinstance(r.source, UpstreamOutput)
+        ]
+        predecessors.extend(n.id for n in dependencies or [])
+        for predecessor in dict.fromkeys(predecessors):
+            self._edges.append(Edge(from_node=predecessor, to_node=id))
+        return NodeRef(
+            id,
+            {
+                p.name: Ref(UpstreamOutput(node_id=id, output=p.name), p.value_schema)
+                for p in declared
+            },
+        )
+
+    def derive(self, id: str, capability: str, **kwargs: Unpack[NodeOptions]) -> NodeRef:
+        return self.node(id, "DERIVE", capability, **kwargs)
+
+    def evaluate(self, id: str, capability: str, **kwargs: Unpack[NodeOptions]) -> NodeRef:
+        return self.node(id, "EVALUATE", capability, **kwargs)
+
+    def control(self, id: str, capability: str, **kwargs: Unpack[NodeOptions]) -> NodeRef:
+        return self.node(id, "CONTROL", capability, **kwargs)
+
+    def aggregate(
+        self,
+        id: str,
+        members: dict[str, Ref],
+        *,
+        reducer: str = "ALL",
+        handling: dict[str, str] | None = None,
+        config: Context | None = None,
+        capability: str = "openverify.aggregate",
+        version: str = "1",
+    ) -> NodeRef:
+        names = list(members)
+        if set(names) & {"subject", "criterion", "members"}:
+            raise ValueError("Reserved aggregate member name")
+        settings: Context = dict(config or {})
+        if capability == "openverify.aggregate":
+            settings.update(
+                reducer=reducer, handling=dict(handling or {k: "REJECT" for k in sorted(HANDLING)})
+            )
+        return self.node(
+            id,
+            "AGGREGATE",
+            capability,
+            version=version,
+            inputs={
+                **members,
+                "members": constant(
+                    cast(JsonValue, names), {"type": "array", "items": {"type": "string"}}
+                ),
+            },
+            aggregate_inputs=names,
+            config=settings,
+        )
+
+    def edge(self, predecessor: NodeRef, successor: NodeRef, *, guard: Guard | None = None) -> None:
+        self._edges = [
+            e for e in self._edges if (e.from_node, e.to_node) != (predecessor.id, successor.id)
+        ]
+        self._edges.append(Edge(from_node=predecessor.id, to_node=successor.id, guard=guard))
+
+    def add_node(self, node: Node) -> NodeRef:
+        self._nodes.append(deepcopy(node))
+        return NodeRef(
+            node.id,
+            {
+                p.name: Ref(UpstreamOutput(node_id=node.id, output=p.name), p.value_schema)
+                for p in node.outputs
+            },
+        )
+
+    def build(self) -> VerificationDefinition:
+        definition = VerificationDefinition(
+            id=self.id,
+            version=self.version,
+            subject=self.subject,
+            criterion=self.criterion,
+            judgment_schema=self.judgment_schema,
+            run_inputs=self._inputs,
+            graph=VCPGraph(nodes=self._nodes, edges=self._edges),
+            execution_policy=self.execution_policy,
+        )
+        return parse_definition(serialize(definition))
+
+    def validate(self) -> None:
+        self.build()
+
+    def inspect(self) -> Context:
+        return inspect_definition(self.build())
+
+    def to_json(self) -> str:
+        return serialize(self.build())

openverify/authoring/references.py

@@ -0,0 +1,21 @@
+"""Typed references compile directly into VCP ValueSource objects."""
+
+from dataclasses import dataclass
+
+from pydantic import JsonValue
+
+from openverify.model import ArtifactRef, Constant, ExternalReference, JsonSchema, ValueSource
+
+
+@dataclass(frozen=True)
+class Ref:
+    source: ValueSource
+    schema: JsonSchema
+
+
+def constant(value: JsonValue, schema: JsonSchema = True) -> Ref:
+    return Ref(Constant(value=value), schema)
+
+
+def external(reference: ArtifactRef) -> Ref:
+    return Ref(ExternalReference(reference=reference), {"type": "object"})

openverify/cli.py

@@ -0,0 +1,58 @@
+"""Non-normative local convenience commands using an explicit demo registry."""
+
+import argparse
+import json
+from pathlib import Path
+from typing import cast
+
+from openverify.adapters.demo import demo_registry
+from openverify.engine import Engine
+from openverify.errors import ProtocolError
+from openverify.inspection import inspect_definition
+from openverify.model import Context
+from openverify.serialization import decode, serialize
+from openverify.validation import parse_definition, parse_object
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Draft Openverify local SDK/reference commands")
+    commands = parser.add_subparsers(dest="command", required=True)
+    validate = commands.add_parser("validate")
+    validate.add_argument("file", type=Path)
+    validate.add_argument("--type", default="verification-definition")
+    inspect = commands.add_parser("inspect")
+    inspect.add_argument("file", type=Path)
+    run = commands.add_parser("run")
+    run.add_argument("file", type=Path)
+    run.add_argument("--run-inputs", type=Path, required=True)
+    run.add_argument("--opportunity-id", required=True)
+    run.add_argument("--output", type=Path)
+    args = parser.parse_args()
+    try:
+        data = cast(Path, args.file).read_bytes()
+        if args.command == "validate":
+            parse_object(args.type, data)
+            print(json.dumps({"valid": True}))
+        elif args.command == "inspect":
+            print(json.dumps(inspect_definition(parse_definition(data)), indent=2))
+        else:
+            run_inputs = decode(cast(Path, args.run_inputs).read_bytes())
+            if not isinstance(run_inputs, dict):
+                raise ProtocolError("PROTOCOL_STRUCTURE", "Run inputs must be a mapping")
+            record = Engine(demo_registry()).run(
+                parse_definition(data),
+                cast(Context, run_inputs),
+                opportunity_id=args.opportunity_id,
+            )
+            output = serialize(record)
+            if args.output:
+                cast(Path, args.output).write_text(output + "\n", encoding="utf-8")
+            else:
+                print(output)
+        return 0
+    except ProtocolError as exc:
+        print(json.dumps(exc.as_dict()))
+        return 1
+    except OSError as exc:
+        print(json.dumps({"code": "IO_ERROR", "message": str(exc)}))
+        return 1

openverify/conformance/__init__.py

@@ -0,0 +1,21 @@
+"""Run a portable manifest using this SDK; no engine execution is required."""
+
+import json
+from pathlib import Path
+
+from openverify.errors import ProtocolError
+from openverify.validation import parse_object
+
+
+def check_manifest(directory: Path) -> list[str]:
+    failures: list[str] = []
+    manifest = json.loads((directory / "manifest.json").read_text(encoding="utf-8"))
+    for case in manifest["cases"]:
+        try:
+            parse_object(case["object_type"], (directory / case["input"]).read_bytes())
+            code = None
+        except ProtocolError as exc:
+            code = exc.code
+        if code != case.get("error_code"):
+            failures.append(case["id"])
+    return failures

openverify/data/profile.json

@@ -0,0 +1,97 @@
+{
+  "protocol": "draft",
+  "id": "standard-draft",
+  "version": "0.1.0",
+  "flattened_statuses": [
+    "PASS",
+    "FAIL",
+    "UNKNOWN",
+    "ERROR",
+    "SKIP"
+  ],
+  "severity_domain": {
+    "id": "standard-draft",
+    "levels": [
+      {
+        "label": "INFO",
+        "rank": 10
+      },
+      {
+        "label": "WARNING",
+        "rank": 20
+      },
+      {
+        "label": "ERROR",
+        "rank": 30
+      },
+      {
+        "label": "BLOCKER",
+        "rank": 40
+      }
+    ]
+  },
+  "aggregators": [
+    "ALL",
+    "ANY",
+    "MAJORITY",
+    "MIN_SCORE",
+    "MAX_SCORE",
+    "AVERAGE",
+    "WEIGHTED_AVERAGE",
+    "WORST_SEVERITY"
+  ],
+  "admission_policies": [
+    "ALWAYS",
+    "PROBABILITY"
+  ],
+  "decisions": [
+    "CONTINUE",
+    "STOP_SUCCESS",
+    "STOP_FAILURE",
+    "ROUTE",
+    "RETRY",
+    "DEFER"
+  ],
+  "resource_dimensions": [
+    {
+      "id": "wall_time",
+      "unit": "s",
+      "description": "Elapsed wall-clock duration"
+    },
+    {
+      "id": "money",
+      "unit": "currency",
+      "description": "Monetary usage; measurement supplies the currency unit"
+    },
+    {
+      "id": "input_tokens",
+      "unit": "token",
+      "description": "Input tokens consumed"
+    },
+    {
+      "id": "output_tokens",
+      "unit": "token",
+      "description": "Output tokens consumed"
+    },
+    {
+      "id": "cpu_time",
+      "unit": "s",
+      "description": "CPU time consumed"
+    },
+    {
+      "id": "gpu_time",
+      "unit": "s",
+      "description": "GPU time consumed"
+    },
+    {
+      "id": "human_time",
+      "unit": "s",
+      "description": "Reviewer time consumed"
+    },
+    {
+      "id": "network_bytes",
+      "unit": "byte",
+      "description": "Network bytes transferred"
+    }
+  ]
+}

openverify/data/schemas/activation.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:verification:draft:activation",
+  "description": "Typed explicit executable dataflow; see spec/draft/dataflow.md.",
+  "type": "object",
+  "properties": {
+    "outcome": {
+      "type": "string",
+      "enum": [
+        "ACTIVATE",
+        "DO_NOT_ACTIVATE"
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "outcome",
+    "reason"
+  ],
+  "additionalProperties": false
+}

openverify/data/schemas/admission.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:verification:draft:admission",
+  "description": "Typed explicit executable dataflow; see spec/draft/dataflow.md.",
+  "type": "object",
+  "properties": {
+    "outcome": {
+      "type": "string",
+      "enum": [
+        "RUN",
+        "SKIP",
+        "DEFER"
+      ]
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "outcome",
+    "reason"
+  ],
+  "additionalProperties": false
+}