1"""

2 CMVK - Cross-Model Verification Kernel

3======================================

4

5 A mathematical and adversarial verification library for calculating

6 drift/hallucination scores between outputs.

7

8 Layer 1: The Primitive

9 Publication Target: PyPI (pip install cmvk)

10

11 This library provides pure functions for verification:

12

13- :func:`verify` - Compare two text outputs for semantic drift

14- :func:`verify_embeddings` - Compare embedding vectors with configurable metrics

15- :func:`verify_distributions` - Compare probability distributions (KL divergence)

16- :func:`verify_sequences` - Compare sequences with alignment

17

18 All functions are pure (no side effects) and use only numpy/scipy.

19

20 Version 0.2.0 Features

21----------------------

22

23- **Configurable Distance Metrics** (CMVK-001/002): Support for cosine, euclidean,

24 manhattan, chebyshev, and mahalanobis distances

25- **Metric Selection API** (CMVK-003): `verify_embeddings(metric="euclidean")`

26- **Batch Verification** (CMVK-004): `verify_embeddings_batch()` for efficiency

27- **Threshold Profiles** (CMVK-005): Pre-configured thresholds for carbon, financial, medical

28- **Audit Trail** (CMVK-006): Immutable logging with timestamps

29- **Dimensional Weighting** (CMVK-008): Weight certain dimensions higher

30- **Explainable Drift** (CMVK-010): Per-dimension contribution analysis

31

32 Example Usage

33-------------

34

35 Basic text verification::

36

37 import cmvk

38

39 score = cmvk.verify(

40 output_a="def add(a, b): return a + b",

41 output_b="def add(x, y): return x + y"

42 )

43 print(f"Drift: {score.drift_score:.2f}") # ~0.15 (low = similar)

44

45 Enhanced embedding comparison with Euclidean distance::

46

47 import cmvk

48 import numpy as np

49

50 # Euclidean distance preserves magnitude - critical for fraud detection

51 claim_vec = np.array([0.82, 150.0]) # Claimed NDVI, carbon

52 obs_vec = np.array([0.316, 95.0]) # Observed values

53

54 score = cmvk.verify_embeddings(

55 claim_vec, obs_vec,

56 metric="euclidean", # Preserves magnitude (CMVK-001)

57 weights=[0.6, 0.4], # NDVI weighted higher (CMVK-008)

58 threshold_profile="carbon", # Domain-specific thresholds (CMVK-005)

59 explain=True # Show dimension contributions (CMVK-010)

60 )

61

62 print(f"Drift: {score.drift_score:.2f}")

63 print(f"Explanation: {score.explanation}")

64

65 Batch verification::

66

67 scores = cmvk.verify_embeddings_batch(

68 claims_vectors,

69 observations_vectors,

70 metric="euclidean",

71 threshold_profile="carbon"

72 )

73 summary = cmvk.aggregate_embedding_scores(scores, threshold_profile="carbon")

74 print(f"Pass rate: {summary['pass_rate']:.1%}")

75

76 For Hugging Face Hub integration, see :mod:`cmvk.hf_utils`.

77"""

78

79 from __future__ import annotations

80

81 from typing import Any

82

83__version__ = "0.2.0"

84__author__ = "Imran Siddique"

85__email__ = "imran.siddique@example.com"

86__license__ = "MIT"

87

88# Audit trail

89 from .audit import AuditEntry, AuditTrail, configure_audit_trail, get_audit_trail

90

91# Distance metrics module

92 from .metrics import (

93 DistanceMetric,

94 MetricResult,

95 calculate_distance,

96 calculate_weighted_distance,

97 get_available_metrics,

98)

99

100# Threshold profiles

101 from .profiles import (

102 ProfileName,

103 ThresholdProfile,

104 create_profile,

105 get_profile,

106 list_profiles,

107 register_profile,

108)

109 from .types import DriftType, VerificationScore

110 from .verification import (

111 DriftExplanation,

112 aggregate_embedding_scores,

113 aggregate_scores,

114 verify,

115 verify_batch,

116 verify_distributions,

117 verify_embeddings,

118 verify_embeddings_batch,

119 verify_sequences,

120)

121

122# Constitutional Validator (CMVK-011)

123 from .constitutional import (

124 ConstitutionalValidator,

125 Principle,

126 PrincipleSet,

127 Severity,

128 Violation,

129 ValidationResult,

130 PrincipleEvaluator,

131 RuleBasedEvaluator,

132 LLMEvaluator,

133 SAFETY_PRINCIPLES,

134 MEDICAL_PRINCIPLES,

135 FINANCIAL_PRINCIPLES,

136 validate_safety,

137 validate_medical,

138 validate_financial,

139)

140

141__all__ = [

142 # Metadata

143 "__version__",

144 "__author__",

145 "__email__",

146 "__license__",

147 # Types (exported for type annotations)

148 "DriftType",

149 "VerificationScore",

150 "DriftExplanation",

151 # Core verification functions

152 "verify",

153 "verify_embeddings",

154 "verify_distributions",

155 "verify_sequences",

156 # Batch operations (CMVK-004)

157 "verify_batch",

158 "verify_embeddings_batch",

159 "aggregate_scores",

160 "aggregate_embedding_scores",

161 # Distance metrics (CMVK-001/002/003)

162 "DistanceMetric",

163 "MetricResult",

164 "calculate_distance",

165 "calculate_weighted_distance",

166 "get_available_metrics",

167 # Threshold profiles (CMVK-005)

168 "ProfileName",

169 "ThresholdProfile",

170 "get_profile",

171 "list_profiles",

172 "create_profile",

173 "register_profile",

174 # Audit trail (CMVK-006)

175 "AuditEntry",

176 "AuditTrail",

177 "get_audit_trail",

178 "configure_audit_trail",

179 # Constitutional Validator (CMVK-011)

180 "ConstitutionalValidator",

181 "Principle",

182 "PrincipleSet",

183 "Severity",

184 "Violation",

185 "ValidationResult",

186 "PrincipleEvaluator",

187 "RuleBasedEvaluator",

188 "LLMEvaluator",

189 "SAFETY_PRINCIPLES",

190 "MEDICAL_PRINCIPLES",

191 "FINANCIAL_PRINCIPLES",

192 "validate_safety",

193 "validate_medical",

194 "validate_financial",

195]

196

197

198 def __getattr__(name: str) -> Any:

199 """Lazy loading for optional submodules."""

200 if name == "hf_utils":

201 from . import hf_utils

202

203 return hf_utils

204 if name == "metrics":

205 from . import metrics

206

207 return metrics

208 if name == "profiles":

209 from . import profiles

210

211 return profiles

212 if name == "audit":

213 from . import audit

214

215 return audit

216 raise AttributeError(f"module {__name__!r} has no attribute {name!r}")