feat(cmvk): port production Cross-Model Verification Kernel from internal

[Imran Siddique (imran-siddique)]

Summary

Ports the production-grade CMVK (Cross-Model Verification Kernel) implementation from the internal agent-governance repository to the public OSS toolkit.

Changes

New Files

• constitutional.py (904L): ConstitutionalValidator with principles, evaluators, and domain-specific validation
• benchmarks.py (478L): Benchmark suite for single-model vs multi-model verification comparison
• profiles.py (300L): Threshold profiles for carbon, financial, medical, strict, and lenient domains

Upgraded Files

• verification.py (956L, was 588L): Added batch verification, explainability engine, audit trail, async support
• metrics.py (473L, was 347L): Added weighted distance functions, enhanced metric computation
• init.py (218L): Re-exports for new modules

Tests

• Comprehensive test suite with 26 test files covering unit, integration, and enhanced feature tests
• All tests pass locally

Tracking

Closes #56

[github-actions]

⚠️ Deprecation Warning: The deny-licenses option is deprecated for possible removal in the next major release. For more information, see issue 997.

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[Copilot]

Pull request overview

This PR ports the production-grade CMVK (Cross-Model Verification Kernel) from an internal repository to the public OSS toolkit. It adds new modules (constitutional validation, threshold profiles, benchmarks), upgrades existing verification and metrics modules from stdlib-only to numpy/scipy, and includes a comprehensive test suite.

Changes:

• Adds constitutional.py (Constitutional AI validator with principles, evaluators, domain-specific validation), profiles.py (threshold profiles for carbon/financial/medical/strict/lenient domains), and benchmarks.py (benchmark suite for single vs multi-model comparison)
• Upgrades verification.py and metrics.py from Python stdlib to numpy/scipy, adding batch verification, explainability engine, audit trail integration, and configurable distance metrics
• Adds 14+ test files across unit and integration test directories, plus updated __init__.py re-exports

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/cmvk/__init__.py	Re-exports new modules (profiles, constitutional), updates version docs
src/cmvk/verification.py	Rewritten with numpy/scipy; adds batch verification, explainability, audit trail, profile integration
src/cmvk/metrics.py	Upgraded to numpy/scipy with enhanced metric implementations and documentation
src/cmvk/profiles.py	New: domain-specific threshold profiles (carbon, financial, medical, etc.)
src/cmvk/constitutional.py	New: Constitutional AI validator with principles, evaluators, and convenience functions
src/cmvk/benchmarks.py	New: Benchmark framework for single-model vs multi-model verification comparison
tests/test_verification.py	Tests for core verification functions
tests/test_enhanced_features.py	Tests for v0.2.0 features (metrics, profiles, batch, explainability, audit)
tests/test_constitutional.py	Tests for constitutional validator
tests/conftest.py	Shared pytest fixtures
tests/unit/test_*.py	Unit tests for kernel, CLI, agents, core types, humaneval loader, visualizer, trace logger, reproducibility
tests/integration/test_*.py	Integration tests for lateral thinking, prosecutor mode, anthropic verifier

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Unused imports: ABC and abstractmethod from abc are imported but never used. Additionally, Sequence and Union from typing are imported but never used. These should be removed to keep the import list clean.

Suggested change

	from abc import ABC, abstractmethod
	from dataclasses import dataclass, field
	from enum import Enum
	from typing import Any, Callable, Optional, Protocol, Sequence, Union
	from dataclasses import dataclass, field
	from enum import Enum
	from typing import Any, Callable, Optional, Protocol

[Copilot]

The docstring example uses severity="medium" (a plain string) instead of Severity.MEDIUM. While Severity inherits from str, the Principle dataclass declares severity: Severity = Severity.MEDIUM, so passing a raw string would not be valid unless the constructor performs coercion. This is misleading documentation that could cause user errors.

[Copilot]

The by_category grouping is stubbed out — the loop body contains only pass, so the returned BenchmarkResults always has empty by_category and by_difficulty dicts. This makes the benchmark results incomplete for users who want to analyze performance by category. If this is intentional as a placeholder, it should be marked with a # TODO comment. Otherwise, the task ID should be mapped to task metadata so results can be properly grouped.

[Copilot]

The profile metric override logic silently replaces the user-specified metric only when the default is "cosine". If a user explicitly passes metric="cosine" together with threshold_profile="carbon" (which defaults to "euclidean"), their explicit choice gets overridden. The condition metric == "cosine" cannot distinguish between "user didn't specify a metric" and "user explicitly chose cosine." Consider using a sentinel value (e.g., metric: str | None = None) to differentiate between "no metric specified" and "explicitly chose cosine."

Suggested change

	# Use profile's default metric if none specified
	if metric == "cosine" and profile.default_metric != "cosine":
	# Use profile's default metric only when no metric was explicitly specified
	if metric is None:

[Copilot]

datetime.utcnow() is deprecated since Python 3.12. The rest of the codebase (e.g., constitutional.py:372, audit.py:18) correctly uses datetime.now(timezone.utc) / datetime.now(UTC). This should be updated to datetime.now(timezone.utc).isoformat() for consistency and to avoid the deprecation warning.

[Copilot]

_string_drift counts every character in a that also appears anywhere in b, which makes the metric insensitive to order and character frequency. For example, _string_drift("aaa", "a") would count common = 3 (all three 'a's match since 'a' in 'a' is true), giving similarity = 6/4 = 1.5 and a negative drift of -0.5. The similarity value can exceed 1.0 when a contains repeated characters that exist in b, producing invalid negative drift values. Consider using len(set(a) & set(b)) for set-based character overlap or a proper sequence similarity measure.