verdictkit 0.1.0__py3-none-any.whl

verdictkit/__init__.py

@@ -0,0 +1,40 @@
+"""verdictkit -- non-custodial verification for agent work.
+
+Local mode (free, unlimited, no API key, no network):
+
+    import verdictkit as vk
+
+    contract = vk.define_contract(
+        task_id="research-042",
+        agent_id="agent-7f3a",
+        intended_action="Summarize the Q3 incident reports into incidents.md",
+        success_criteria=[
+            {"id": "c1", "type": "file_exists", "path": "incidents.md",
+             "description": "summary file was written"},
+        ],
+    )
+    result = vk.verify_run(contract, base_path="./output")  # PASS | FLAG | FAIL
+
+Hosted mode (reputation ledger + cross-machine re-verification):
+
+    client = vk.Client(api_key="vk_live_...")
+    contract_id = client.create_contract(contract)
+    bundle = vk.collect_evidence(contract, base_path="./output")
+    verdict = client.submit_run(contract_id, bundle)
+"""
+from .contracts import define_contract
+from .verdict import verify_run, Verdict
+from .evidence import collect_evidence, verify_bundle_hash
+from .client import Client, VerdictkitError, AuthError
+
+__version__ = "0.1.0"
+__all__ = [
+    "define_contract",
+    "verify_run",
+    "Verdict",
+    "collect_evidence",
+    "verify_bundle_hash",
+    "Client",
+    "VerdictkitError",
+    "AuthError",
+]

verdictkit/checks.py

@@ -0,0 +1,92 @@
+"""Deterministic checks (stdlib only). Never raise; errors are results."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import sqlite3
+
+
+def _expand(p): return os.path.expanduser(os.path.expandvars(p))
+def _r(c, s, e): return {"check_id": c["id"], "type": c["type"], "status": s, "evidence": e}
+
+
+def _file_exists(c):
+    p = _expand(c["path"])
+    ok = os.path.isfile(p)
+    return _r(c, "pass" if ok else "fail", f"{'found' if ok else 'MISSING'}: {p}")
+
+def _file_nonempty(c):
+    p = _expand(c["path"])
+    if not os.path.isfile(p): return _r(c, "fail", f"MISSING: {p}")
+    n = os.path.getsize(p)
+    return _r(c, "pass" if n > 0 else "fail", f"{p} size={n}")
+
+def _file_contains(c):
+    p = _expand(c["path"])
+    try: rx = re.compile(c["pattern"])
+    except re.error as e: return _r(c, "error", f"bad regex: {e}")
+    try:
+        with open(p, errors="replace") as f: text = f.read()
+    except OSError as e: return _r(c, "fail", f"cannot read {p}: {e}")
+    hit = rx.search(text) is not None
+    return _r(c, "pass" if hit else "fail", f"pattern {'found in' if hit else 'NOT FOUND in'} {p}")
+
+def _dir_exists(c):
+    p = _expand(c["path"])
+    ok = os.path.isdir(p)
+    return _r(c, "pass" if ok else "fail", f"{'found dir' if ok else 'MISSING dir'}: {p}")
+
+def _json_valid(c):
+    p = _expand(c["path"])
+    try:
+        with open(p, errors="replace") as f: json.load(f)
+        return _r(c, "pass", f"valid JSON: {p}")
+    except OSError as e: return _r(c, "fail", f"cannot read {p}: {e}")
+    except json.JSONDecodeError as e: return _r(c, "fail", f"invalid JSON: {e}")
+
+def _line_count_gte(c):
+    p = _expand(c["path"]); m = int(c.get("min_lines", 1))
+    try:
+        with open(p, errors="replace") as f: n = sum(1 for _ in f)
+    except OSError as e: return _r(c, "fail", f"cannot read {p}: {e}")
+    return _r(c, "pass" if n >= m else "fail", f"{p}: {n} lines, need >={m}")
+
+def _sqlite_table_has_rows(c):
+    db, table, m = _expand(c["db"]), c["table"], int(c.get("min_rows", 1))
+    if not re.fullmatch(r"[A-Za-z_][A-Za-z0-9_]*", table):
+        return _r(c, "error", f"unsafe table name {table!r}")
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+        n = con.execute(f'SELECT COUNT(*) FROM "{table}"').fetchone()[0]
+        con.close()
+    except Exception as e: return _r(c, "error", f"cannot query: {e}")
+    return _r(c, "pass" if n >= m else "fail", f"{table}: {n} rows, need >={m}")
+
+def _path_absent(c):
+    p = _expand(c["path"]); gone = not os.path.exists(p)
+    return _r(c, "pass" if gone else "fail", f"{'absent' if gone else 'PRESENT (scope violation)'}: {p}")
+
+def _pattern_count_gte(c):
+    p = _expand(c["path"]); m = int(c.get("min_count", 1))
+    try: rx = re.compile(c["pattern"], re.MULTILINE)
+    except re.error as e: return _r(c, "error", f"bad regex: {e}")
+    try:
+        with open(p, errors="replace") as f: n = len(rx.findall(f.read()))
+    except OSError as e: return _r(c, "fail", f"cannot read {p}: {e}")
+    return _r(c, "pass" if n >= m else "fail", f"{n} matches in {p}, need >={m}")
+
+RUNNERS = {
+    "file_exists": _file_exists, "file_nonempty": _file_nonempty,
+    "file_contains": _file_contains, "dir_exists": _dir_exists,
+    "json_valid": _json_valid, "line_count_gte": _line_count_gte,
+    "sqlite_table_has_rows": _sqlite_table_has_rows,
+    "path_absent": _path_absent, "pattern_count_gte": _pattern_count_gte,
+}
+
+def run_check(criterion):
+    r = RUNNERS.get(criterion["type"])
+    if r is None:
+        return _r(criterion, "error", f"no runner for {criterion['type']!r}")
+    try: return r(criterion)
+    except Exception as e: return _r(criterion, "error", f"runner crashed: {e}")

verdictkit/cli.py

@@ -0,0 +1,54 @@
+"""Minimal CLI: `verdictkit verify <contract.json> [--base-path DIR]`."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import verify_run, Verdict, __version__
+
+EXIT = {Verdict.PASS: 0, Verdict.FAIL: 1, Verdict.FLAG: 2}
+
+
+def cmd_verify(args) -> int:
+    try:
+        with open(args.contract, encoding="utf-8") as f:
+            contract = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        print(f"error: cannot read contract {args.contract}: {e}",
+              file=sys.stderr)
+        return 3
+    result = verify_run(contract, base_path=args.base_path)
+    print(f"verdict: {result['verdict']}")
+    print(f"reason:  {result['reason']}")
+    if args.verbose:
+        for r in result["check_results"]:
+            print(f"  [{r['status']:>5}] {r['check_id']} ({r['type']}): {r['evidence']}")
+        for claim in result["unverifiable_claims"]:
+            print(f"  [claim] {claim}")
+    return EXIT.get(result["verdict"], 3)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="verdictkit",
+        description="Non-custodial verification for agent work (local, free).")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+    v = sub.add_parser("verify", help="Verify a contract JSON file locally.")
+    v.add_argument("contract", help="Path to a contract JSON file.")
+    v.add_argument("--base-path", default=None,
+                   help="Resolve relative criterion paths against this directory.")
+    v.add_argument("-v", "--verbose", action="store_true",
+                   help="Show per-check evidence.")
+    v.set_defaults(func=cmd_verify)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

verdictkit/client.py

@@ -0,0 +1,124 @@
+"""Client for the hosted verdictkit API.
+
+The hosted tier adds what local verification cannot: cross-machine
+evidence re-verification, a third-party-queryable verdict registry
+(reputation ledger), webhooks on FAIL, and pay-per-verification billing.
+
+Local verification (verdictkit.verify_run) is always free, unlimited, and
+needs no API key and no network. This client is only for the hosted tier.
+
+    import verdictkit as vk
+    client = vk.Client(api_key="vk_live_...")          # or base_url=...
+    contract_id = client.create_contract(contract)
+    verdict = client.submit_run(contract_id, evidence_bundle)
+"""
+from __future__ import annotations
+
+import requests
+
+# ---------------------------------------------------------------------------
+# PLACEHOLDER: production API URL is not yet assigned. Update this constant
+# (and release 0.2.0) once the hosted API ships. Until then, Client can be
+# pointed at a dev/staging host via the base_url argument.
+# ---------------------------------------------------------------------------
+DEFAULT_BASE_URL = "https://api.verdictkit.dev/v1"
+
+
+class VerdictkitError(Exception):
+    """Base error for hosted-API failures (network, timeout, bad response)."""
+
+
+class AuthError(VerdictkitError):
+    """Raised on HTTP 401/403 -- the API key was rejected."""
+
+
+class Client:
+    """Thin HTTP client for the hosted verdictkit API."""
+
+    def __init__(self, api_key: str, base_url: str = DEFAULT_BASE_URL,
+                 timeout: float = 30.0):
+        if not api_key:
+            raise ValueError("api_key is required for the hosted verdictkit API. "
+                             "For local verification with no key and no network, "
+                             "use verdictkit.verify_run() instead.")
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "User-Agent": f"verdictkit-py/{__import__('verdictkit').__version__}",
+        })
+
+    # -- internals ----------------------------------------------------------
+    def _request(self, method: str, path: str, **kwargs):
+        url = f"{self.base_url}{path}"
+        try:
+            resp = self._session.request(method, url,
+                                         timeout=self.timeout, **kwargs)
+        except requests.RequestException as e:
+            raise VerdictkitError(
+                f"could not reach verdictkit API at {url}: {e}") from e
+        if resp.status_code in (401, 403):
+            raise AuthError(
+                f"verdictkit API rejected the credentials (HTTP {resp.status_code}). "
+                "Check your API key.")
+        if not resp.ok:
+            detail = self._safe_error_detail(resp)
+            raise VerdictkitError(
+                f"verdictkit API returned HTTP {resp.status_code}: {detail}")
+        try:
+            return resp.json()
+        except ValueError as e:
+            raise VerdictkitError(
+                f"verdictkit API returned non-JSON response (HTTP {resp.status_code})"
+            ) from e
+
+    @staticmethod
+    def _safe_error_detail(resp) -> str:
+        try:
+            data = resp.json()
+            if isinstance(data, dict):
+                return str(data.get("error") or data.get("message") or data)[:300]
+        except ValueError:
+            pass
+        return (resp.text or "(empty body)")[:300]
+
+    # -- public API ----------------------------------------------------------
+    def create_contract(self, contract: dict) -> str:
+        """Register a contract with the hosted API. Returns the contract_id."""
+        data = self._request("POST", "/contracts", json=contract)
+        try:
+            return data["contract_id"]
+        except (TypeError, KeyError) as e:
+            raise VerdictkitError(
+                f"verdictkit API /contracts response missing 'contract_id': {data!r}"
+            ) from e
+
+    def submit_run(self, contract_id: str, evidence_bundle: dict) -> dict:
+        """Submit an evidence bundle for a run; returns the server verdict.
+
+        The server re-runs the deterministic checks against the
+        content-addressed evidence in the bundle -- it never trusts the
+        agent's claims alone.
+        """
+        return self._request(
+            "POST", f"/contracts/{contract_id}/runs",
+            json={"evidence_bundle": evidence_bundle})
+
+    def get_verdict(self, contract_id: str) -> dict:
+        """Fetch the latest verdict for a contract."""
+        return self._request("GET", f"/contracts/{contract_id}/verdict")
+
+    def list_verdicts(self, agent_id: str | None = None,
+                      limit: int = 100) -> list:
+        """List recent verdicts, optionally filtered to one agent."""
+        params = {"limit": limit}
+        if agent_id is not None:
+            params["agent_id"] = agent_id
+        data = self._request("GET", "/verdicts", params=params)
+        if not isinstance(data, list):
+            raise VerdictkitError(
+                f"verdictkit API /verdicts response was not a list: {data!r}")
+        return data

verdictkit/contracts.py

@@ -0,0 +1,37 @@
+"""Task contracts: the machine-readable promise an agent run is checked against."""
+from __future__ import annotations
+
+import datetime
+import uuid
+
+CHECK_TYPES = {
+    "file_exists", "file_nonempty", "file_contains", "dir_exists",
+    "json_valid", "line_count_gte", "sqlite_table_has_rows", "path_absent",
+    "pattern_count_gte",
+}
+
+
+def define_contract(task_id, agent_id, intended_action, success_criteria,
+                    scope=None, unverifiable_claims=None, principal="unknown"):
+    """Create a validated contract dict.
+
+    success_criteria: list of {"id", "type", "description", ...check params}.
+    Anything that cannot be checked deterministically belongs in
+    unverifiable_claims (yields FLAG, never silent PASS).
+    """
+    for i, c in enumerate(success_criteria):
+        if not isinstance(c, dict) or "type" not in c or "id" not in c:
+            raise ValueError(f"criterion {i} needs 'id' and 'type'")
+        if c["type"] not in CHECK_TYPES:
+            raise ValueError(f"unknown check type {c['type']!r}")
+    return {
+        "contract_id": f"vc_{uuid.uuid4().hex[:12]}",
+        "task_id": task_id,
+        "agent_id": agent_id,
+        "principal": principal,
+        "created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "intended_action": intended_action,
+        "scope": scope or {},
+        "success_criteria": success_criteria,
+        "unverifiable_claims": unverifiable_claims or [],
+    }

verdictkit/evidence.py

@@ -0,0 +1,166 @@
+"""Evidence bundles: the trust model of hosted verification.
+
+The hosted API never trusts the agent's claims. Instead, the agent (or its
+harness) captures *content-addressed evidence* locally -- file bytes with
+their sha256, directory listings, parsed JSON -- into a bundle, and the
+server re-runs the deterministic checks against the bundle's content.
+
+Integrity: every artifact carries a sha256 of its full bytes, and
+``bundle_hash`` is a sha256 over the canonical JSON of all artifacts. The
+server recomputes both; tampering breaks the hashes.
+
+Limits: per-artifact byte caps keep bundles small. Truncated artifacts are
+marked ``truncated: true`` -- the server treats checks it cannot fully
+re-run as FLAG, never as PASS. A missing or unreadable artifact is
+recorded honestly (``exists: false`` / ``collection_error``); absence of
+evidence can only downgrade a verdict, never upgrade it.
+"""
+from __future__ import annotations
+
+import base64
+import datetime
+import hashlib
+import json
+import os
+import sqlite3
+
+EVIDENCE_SCHEMA = "verdictkit-evidence/1"
+MAX_ARTIFACT_BYTES = 256 * 1024   # 256 KiB of file content per artifact
+MAX_DIR_ENTRIES = 2000
+
+
+def _sha256_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _resolve(path: str, base_path: str | None) -> str:
+    p = os.path.expanduser(os.path.expandvars(path))
+    if base_path and not os.path.isabs(p):
+        p = os.path.join(base_path, p)
+    return os.path.normpath(p)
+
+
+def _file_artifact(path: str) -> dict:
+    art: dict = {"kind": "file", "path": path, "exists": False}
+    if not os.path.isfile(path):
+        return art
+    art["exists"] = True
+    size = os.path.getsize(path)
+    art["size"] = size
+    # Full-file hash by streaming, even when content is truncated below.
+    h = hashlib.sha256()
+    with open(path, "rb") as f:
+        for chunk in iter(lambda: f.read(65536), b""):
+            h.update(chunk)
+    art["full_sha256"] = h.hexdigest()
+    art["truncated"] = size > MAX_ARTIFACT_BYTES
+    with open(path, "rb") as f:
+        raw = f.read(MAX_ARTIFACT_BYTES)
+    art["sha256"] = _sha256_bytes(raw)
+    try:
+        art["content"] = raw.decode("utf-8")
+        art["content_encoding"] = "text"
+        art["line_count"] = art["content"].count("\n") + (1 if art["content"] else 0)
+    except UnicodeDecodeError:
+        art["content"] = base64.b64encode(raw).decode("ascii")
+        art["content_encoding"] = "base64"
+        art["line_count"] = None
+    return art
+
+
+def _dir_artifact(path: str) -> dict:
+    art: dict = {"kind": "dir", "path": path, "exists": os.path.isdir(path)}
+    if art["exists"]:
+        try:
+            names = sorted(os.listdir(path))
+        except OSError as e:
+            return {**art, "collection_error": str(e)}
+        art["listing_truncated"] = len(names) > MAX_DIR_ENTRIES
+        art["listing"] = names[:MAX_DIR_ENTRIES]
+    return art
+
+
+def _sqlite_artifact(db: str, table: str) -> dict:
+    art: dict = {"kind": "sqlite", "db": db, "table": table,
+                 "db_exists": os.path.isfile(db), "row_count": None}
+    if not art["db_exists"]:
+        return art
+    if not table.replace("_", "").isalnum() or table[0].isdigit():
+        art["collection_error"] = f"unsafe table name {table!r}"
+        return art
+    try:
+        con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+        art["row_count"] = con.execute(
+            f'SELECT COUNT(*) FROM "{table}"').fetchone()[0]
+        art["tables"] = [r[0] for r in
+                         con.execute("SELECT name FROM sqlite_master "
+                                     "WHERE type='table' ORDER BY name")]
+        con.close()
+    except Exception as e:  # recorded, never raised
+        art["collection_error"] = str(e)
+    return art
+
+
+def _absence_artifact(path: str) -> dict:
+    return {"kind": "absence", "path": path,
+            "exists": os.path.exists(path)}
+
+
+_FILE_CHECK_TYPES = {"file_exists", "file_nonempty", "file_contains",
+                     "json_valid", "line_count_gte", "pattern_count_gte"}
+
+
+def collect_evidence(contract: dict, base_path: str | None = None) -> dict:
+    """Walk the contract's success_criteria and capture artifacts locally.
+
+    Returns a bundle dict the hosted API can re-verify:
+
+        {"schema": "verdictkit-evidence/1", "contract_id": ..., "task_id": ...,
+         "agent_id": ..., "success_criteria": [...], "artifacts": {check_id: ...},
+         "created_at": ..., "bundle_hash": "sha256..."}
+
+    Relative paths in criteria are resolved against ``base_path``.
+    Collects only -- never runs the verdict rubric and never touches the
+    network.
+    """
+    criteria = contract.get("success_criteria", [])
+    artifacts = {}
+    for c in criteria:
+        ctype = c.get("type")
+        cid = c.get("id")
+        if ctype in _FILE_CHECK_TYPES:
+            artifacts[cid] = _file_artifact(_resolve(c.get("path", ""), base_path))
+        elif ctype == "dir_exists":
+            artifacts[cid] = _dir_artifact(_resolve(c.get("path", ""), base_path))
+        elif ctype == "sqlite_table_has_rows":
+            artifacts[cid] = _sqlite_artifact(
+                _resolve(c.get("db", ""), base_path), c.get("table", ""))
+        elif ctype == "path_absent":
+            artifacts[cid] = _absence_artifact(_resolve(c.get("path", ""), base_path))
+        else:
+            artifacts[cid] = {"kind": "unknown",
+                              "collection_error": f"no collector for {ctype!r}"}
+    canonical = json.dumps(artifacts, sort_keys=True, separators=(",", ":"),
+                           default=str)
+    bundle = {
+        "schema": EVIDENCE_SCHEMA,
+        "contract_id": contract.get("contract_id"),
+        "task_id": contract.get("task_id"),
+        "agent_id": contract.get("agent_id"),
+        "success_criteria": criteria,
+        "base_path": os.path.abspath(base_path) if base_path else None,
+        "artifacts": artifacts,
+        "created_at": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+        "bundle_hash": _sha256_bytes(canonical.encode("utf-8")),
+    }
+    return bundle
+
+
+def verify_bundle_hash(bundle: dict) -> bool:
+    """Recompute the bundle hash; False means the bundle was tampered with."""
+    artifacts = bundle.get("artifacts")
+    if not isinstance(artifacts, dict):
+        return False
+    canonical = json.dumps(artifacts, sort_keys=True, separators=(",", ":"),
+                           default=str)
+    return _sha256_bytes(canonical.encode("utf-8")) == bundle.get("bundle_hash")

verdictkit/verdict.py

@@ -0,0 +1,63 @@
+"""Rubric: FAIL if any check fails; FLAG if anything is unverifiable or
+errored (or there was nothing checkable); PASS only on clean checks.
+
+verify_run is local-first: no API key, no network, no cost. Pass
+``base_path`` to resolve relative criterion paths against a directory
+instead of the current working directory.
+"""
+from __future__ import annotations
+
+import os
+
+from .checks import run_check
+
+_PATH_KEYS = ("path", "db")
+
+
+def _resolve_criteria(contract, base_path):
+    """Copy criteria with relative paths resolved against base_path."""
+    resolved = []
+    for c in contract.get("success_criteria", []):
+        c = dict(c)
+        for key in _PATH_KEYS:
+            p = c.get(key)
+            if isinstance(p, str) and not os.path.isabs(
+                    os.path.expanduser(os.path.expandvars(p))):
+                c[key] = os.path.normpath(os.path.join(base_path, p))
+        resolved.append(c)
+    return resolved
+
+
+class Verdict:
+    PASS = "PASS"
+    FLAG = "FLAG"
+    FAIL = "FAIL"
+
+
+def verify_run(contract, base_path=None):
+    """Run the deterministic checks locally and return the verdict dict.
+
+    No API key, no network, free and unlimited. ``base_path`` resolves
+    relative criterion paths against a directory (default: cwd).
+    """
+    criteria = (_resolve_criteria(contract, base_path)
+                if base_path else contract.get("success_criteria", []))
+    results = [run_check(c) for c in criteria]
+    unverifiable = contract.get("unverifiable_claims", [])
+    failed = [r for r in results if r["status"] == "fail"]
+    errored = [r for r in results if r["status"] == "error"]
+    if failed:
+        verdict, reason = Verdict.FAIL, "; ".join(r["evidence"] for r in failed)
+    elif errored or unverifiable or not results:
+        parts = []
+        if not results: parts.append("no checkable success criteria")
+        if errored: parts.append("; ".join(r["evidence"] for r in errored))
+        if unverifiable: parts.append(f"{len(unverifiable)} unverifiable claim(s)")
+        verdict, reason = Verdict.FLAG, ". ".join(parts)
+    else:
+        verdict = Verdict.PASS
+        reason = f"all {len(results)} checks passed"
+    return {"contract_id": contract["contract_id"], "task_id": contract["task_id"],
+            "agent_id": contract["agent_id"], "verdict": verdict,
+            "reason": reason, "check_results": results,
+            "unverifiable_claims": unverifiable}

verdictkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: verdictkit
+Version: 0.1.0
+Summary: Non-custodial verification for agent work: did the agent do what it said?
+Author: agentbuilt
+License: MIT
+Project-URL: Homepage, https://github.com/mattedwardseo/verdictkit
+Project-URL: Documentation, https://github.com/mattedwardseo/verdictkit#readme
+Project-URL: Repository, https://github.com/mattedwardseo/verdictkit
+Project-URL: Issues, https://github.com/mattedwardseo/verdictkit/issues
+Keywords: agents,verification,ai-safety,auditing,deterministic-checks
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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 :: Software Development :: Testing
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+
+# verdictkit
+
+Non-custodial verification for agent work. Answers one question: **did the
+agent do what it said it would?**
+
+The product is the *verification layer*, not custody: a machine-readable
+contract (intended action + checkable success criteria), deterministic
+checks against the world, and a rubric verdict — `PASS` / `FLAG` / `FAIL`
+— with evidence. No money moves through it, so there is no money-transmitter
+licensing wall. That is the whole strategic point.
+
+**Status: 0.1.0, launch-ready, NOT published to PyPI.** Do not run the
+publish command without approval.
+
+## Quickstart
+
+```bash
+pip install verdictkit        # not on PyPI yet; use: pip install .
+```
+
+### Local verification (free, unlimited, no key, no network)
+
+```python
+import verdictkit as vk
+
+contract = vk.define_contract(
+    task_id="research-042",
+    agent_id="agent-7f3a",
+    intended_action="Summarize the Q3 incident reports into incidents.md",
+    success_criteria=[
+        {"id": "c1", "type": "file_exists",
+         "path": "incidents.md",
+         "description": "summary file was written"},
+        {"id": "c2", "type": "pattern_count_gte",
+         "path": "incidents.md",
+         "pattern": r"^## Incident",
+         "min_count": 3,
+         "description": "covers at least 3 incidents"},
+    ],
+    unverifiable_claims=["tone is executive-appropriate"],  # -> FLAG, honestly
+)
+
+result = vk.verify_run(contract, base_path="./output")
+print(result["verdict"])   # PASS | FLAG | FAIL
+print(result["reason"])    # evidence, always
+```
+
+Or from the shell:
+
+```bash
+verdictkit verify contract.json --base-path ./output -v
+# exit code: 0 = PASS, 1 = FAIL, 2 = FLAG, 3 = usage/IO error
+```
+
+### Hosted verification (reputation ledger + re-verification)
+
+Local mode checks *your* machine. The hosted tier lets a third party trust
+the verdict: you capture evidence locally, the server **re-runs the
+deterministic checks against the evidence** — it never trusts the agent's
+claims alone.
+
+```python
+import verdictkit as vk
+
+client = vk.Client(api_key="vk_live_...")          # base_url=... to override
+contract_id = client.create_contract(contract)      # -> "vc_..."
+bundle = vk.collect_evidence(contract, base_path="./output")
+verdict = client.submit_run(contract_id, bundle)    # server-side verdict dict
+
+client.get_verdict(contract_id)                     # latest verdict
+client.list_verdicts(agent_id="agent-7f3a")         # reputation ledger
+```
+
+Errors are clean: `vk.AuthError` on bad credentials (401/403),
+`vk.VerdictkitError` on network trouble, timeouts, or bad responses.
+
+## API reference
+
+| Symbol | Kind | Description |
+|---|---|---|
+| `vk.define_contract(task_id, agent_id, intended_action, success_criteria, scope=None, unverifiable_claims=None, principal="unknown")` | function | Build a validated contract dict. Raises `ValueError` on unknown check types or criteria missing `id`/`type`. |
+| `vk.verify_run(contract, base_path=None)` | function | Run all checks locally, return verdict dict. No key, no network. `base_path` resolves relative criterion paths. |
+| `vk.Verdict` | class | Constants `PASS`, `FLAG`, `FAIL`. |
+| `vk.collect_evidence(contract, base_path=None)` | function | Capture a content-addressed evidence bundle (file bytes + sha256, dir listings, parsed JSON, sqlite row counts). Local only, no network. |
+| `vk.verify_bundle_hash(bundle)` | function | Recompute `bundle_hash`; `False` means the bundle was tampered with. |
+| `vk.Client(api_key, base_url=..., timeout=30.0)` | class | Hosted API client. `create_contract(contract) -> contract_id`, `submit_run(contract_id, evidence_bundle) -> verdict dict`, `get_verdict(contract_id) -> dict`, `list_verdicts(agent_id=None, limit=100) -> list`. Raises `ValueError` without an API key. |
+| `vk.VerdictkitError` | exception | Base error: network, timeout, bad server response. |
+| `vk.AuthError(VerdictkitError)` | exception | 401/403 from the API. |
+
+### Verdict shape
+
+```python
+{"contract_id": ..., "task_id": ..., "agent_id": ...,
+ "verdict": "PASS" | "FLAG" | "FAIL",
+ "reason": "human-readable evidence summary",
+ "check_results": [{"check_id": ..., "type": ..., "status": "pass"|"fail"|"error",
+                    "evidence": ...}, ...],
+ "unverifiable_claims": [...]}
+```
+
+### Check types
+
+`file_exists` · `file_nonempty` · `file_contains` (regex) ·
+`pattern_count_gte` · `dir_exists` · `json_valid` · `line_count_gte` ·
+`sqlite_table_has_rows` · `path_absent` (scope guard)
+
+## The rubric
+
+- **FAIL** — any check fails. Fail dominates everything else.
+- **FLAG** — no failures, but something couldn't be verified: a check
+  errored, a claim was declared unverifiable, or there was nothing
+  checkable at all.
+- **PASS** — every check passed cleanly, and nothing was left unverifiable.
+
+Design rule: a check that cannot run is an *error*, never a pass. A run
+with nothing checkable can at best be *flagged*. Absence of evidence is
+never evidence of success.
+
+## Trust model
+
+1. **Contracts are machine-readable promises.** What the agent intended to
+   do, written before the run, with deterministic success criteria.
+2. **Evidence is content-addressed.** `collect_evidence` captures file
+   bytes with their sha256, directory listings, and query results. The
+   bundle carries a `bundle_hash` over canonical JSON — the server
+   recomputes every hash; tampering breaks them.
+3. **The server re-runs checks; it never trusts claims.** Hosted
+   verification executes the same deterministic check engine against the
+   bundle's content. Claims without evidence stay in
+   `unverifiable_claims` and can only produce FLAG.
+4. **Truncation is honest.** Artifacts are capped (256 KiB file content,
+   2000 dir entries). Truncated artifacts are marked, and checks the
+   server cannot fully re-run become FLAG — never PASS.
+
+## What verification is NOT
+
+- **Not a guarantee of quality.** PASS means the deterministic criteria
+  were met — the file exists, has ≥3 sections, parses as JSON. It says
+  nothing about whether the writing is good, the code is correct, or the
+  summary is accurate. Put anything subjective in `unverifiable_claims`
+  and accept the FLAG honestly.
+- **Not an oracle.** Checks only see what they can read: files, dirs,
+  sqlite. They cannot verify "the user is happy" or "the bug is fixed"
+  unless that was operationalized into a checkable artifact.
+- **Not custody, not escrow.** No money moves through verdictkit; it
+  attests to work done, it does not hold funds or release payment.
+- **Not tamper-proof on a compromised machine.** Local verification trusts
+  the local filesystem. The hosted tier raises the bar (content-addressed
+  bundles, server-side re-runs, reputation ledger) but a fully
+  compromised agent host can still fake the inputs. Verification makes
+  lying *auditable*, not impossible.
+
+## Development
+
+```bash
+pip install -e ".[dev]"   # dev extras: pytest, build
+python3 -m pytest         # 59 tests, all local, no network
+python3 -m build          # wheel/sdist -- DO NOT upload without approval
+```
+
+## License
+
+MIT. See `LICENSE`.

verdictkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+verdictkit/__init__.py,sha256=IqtA15Mh7kji3dk2mbD-rqaiVfhEYpfdFeYJcZmVwik,1253
+verdictkit/checks.py,sha256=57nfWtMUL7XaXEBckkV5o0Bt0PJ5ij-3mkFZiVNoBS0,3696
+verdictkit/cli.py,sha256=11WvxAJr5QGrDAShg-3orkarmCCrDtgfo1k2E2EGeIo,1907
+verdictkit/client.py,sha256=4Pod_lJRyC9pwt73ZFhM08mnKgW5MEnnVgVA341OwDI,5215
+verdictkit/contracts.py,sha256=G81Ix1wrgXJZtixu7Q6f4zOe5oJDSkoDuPGeqoNMkaM,1456
+verdictkit/evidence.py,sha256=t4qEAgfQU7Uf4oW7v5-E-ksAF1IM7-6Yg7ukfxsn4j0,6498
+verdictkit/verdict.py,sha256=KzxDfzLRwmw0mt8yjl2ZCfAtH4aXWZ7ad8h6-VXorJQ,2418
+verdictkit-0.1.0.dist-info/METADATA,sha256=OelZtbFloIqqy6F2rurTJGx0ufww12_G4ns06nez6Pg,8275
+verdictkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+verdictkit-0.1.0.dist-info/entry_points.txt,sha256=pL3SfNWtPRuAO43FEX3skoULazvSFM_HVTJzNw0o3vI,51
+verdictkit-0.1.0.dist-info/top_level.txt,sha256=iv3wlK6trZ6ak0yC5q60eCj8COQGtMiNNOq8CMW8-v0,11
+verdictkit-0.1.0.dist-info/RECORD,,

verdictkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

verdictkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+verdictkit = verdictkit.cli:main

verdictkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+verdictkit