ct-toolkit 0.2.1__tar.gz → 0.2.2__tar.gz

{ct_toolkit-0.2.1 → ct_toolkit-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.2.1
+Version: 0.2.2
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0
@@ -28,6 +28,8 @@ Provides-Extra: autogen
 Requires-Dist: pyautogen>=0.4.0; extra == "autogen"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Provides-Extra: ml
+Requires-Dist: torch>=2.0.0; extra == "ml"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

{ct_toolkit-0.2.1 → ct_toolkit-0.2.2}/ct_toolkit/core/wrapper.py

@@ -250,6 +250,7 @@ class TheseusWrapper:
             l3_threshold=self._config.divergence_l3_threshold,
             enterprise_mode=self._config.enterprise_mode,
             scheduler=scheduler,
+            provenance_log=self._provenance_log,
         )
 
     def _log_init(self) -> None:
@@ -535,6 +536,10 @@ class TheseusWrapper:
     def compatibility(self) -> CompatibilityResult:
         return self._compatibility
 
+    @property
+    def divergence_engine(self) -> Any:
+        return self._divergence_engine
+
     def __repr__(self) -> str:
         return (
             f"TheseusWrapper("

ct_toolkit-0.2.2/ct_toolkit/divergence/loss.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from typing import Any
+
+class DivergencePenaltyLoss(nn.Module):
+    """
+    Implements the Divergence Penalty as defined in Section 5.1 of the research paper.
+    
+    This loss function penalizes normative drift by calculating the distance between
+    the model's generated embeddings and a reference 'Kernel' embedding.
+    """
+    def __init__(self, alpha: float = 1.0, distance_metric: str = "cosine"):
+        super().__init__()
+        self.alpha = alpha
+        self.distance_metric = distance_metric
+
+    def forward(
+        self, 
+        current_embeddings: torch.Tensor, 
+        reference_embeddings: torch.Tensor
+    ) -> torch.Tensor:
+        """
+        Calculates the identity-divergence penalty.
+        
+        Args:
+            current_embeddings: The hidden states or outputs of the model being trained.
+            reference_embeddings: The frozen CIK (Constitutional Identity Kernel) embeddings.
+            
+        Returns:
+            A scalar tensor representing the penalty.
+        """
+        if self.distance_metric == "cosine":
+            # 1 - cosine_similarity (range: 0 to 2, where 0 is identical)
+            similarity = F.cosine_similarity(current_embeddings, reference_embeddings, dim=-1)
+            dist = 1.0 - similarity
+        else:
+            # Fallback to MSE / Euclidean distance
+            dist = F.mse_loss(current_embeddings, reference_embeddings, reduction='none')
+            if dist.dim() > 1:
+                dist = dist.mean(dim=-1)
+            
+        # Penalize drift beyond a certain magnitude
+        penalty = self.alpha * torch.mean(dist)
+        
+        return penalty
+
+def compute_alignment_loss(
+    model_output_embeddings: torch.Tensor,
+    kernel_anchor_embeddings: torch.Tensor,
+    alpha: float = 0.5
+) -> torch.Tensor:
+    """
+    Helper function to compute identity alignment loss during training.
+    """
+    criterion = DivergencePenaltyLoss(alpha=alpha)
+    return criterion(model_output_embeddings, kernel_anchor_embeddings)

{ct_toolkit-0.2.1 → ct_toolkit-0.2.2}/ct_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.2.1
+Version: 0.2.2
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0
@@ -28,6 +28,8 @@ Provides-Extra: autogen
 Requires-Dist: pyautogen>=0.4.0; extra == "autogen"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
+Provides-Extra: ml
+Requires-Dist: torch>=2.0.0; extra == "ml"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

{ct_toolkit-0.2.1 → ct_toolkit-0.2.2}/ct_toolkit.egg-info/SOURCES.txt

@@ -17,6 +17,7 @@ ct_toolkit/divergence/analysis.py
 ct_toolkit/divergence/engine.py
 ct_toolkit/divergence/l2_judge.py
 ct_toolkit/divergence/l3_icm.py
+ct_toolkit/divergence/loss.py
 ct_toolkit/divergence/scheduler.py
 ct_toolkit/endorsement/__init__.py
 ct_toolkit/endorsement/reflective.py
@@ -32,4 +33,5 @@ ct_toolkit/provenance/log.py
 ct_toolkit/provenance/vault/__init__.py
 ct_toolkit/utils/__init__.py
 ct_toolkit/utils/logger.py
-tests/test_analysis.py
+tests/test_analysis.py
+tests/test_loss.py

{ct_toolkit-0.2.1 → ct_toolkit-0.2.2}/ct_toolkit.egg-info/requires.txt

@@ -27,5 +27,8 @@ mkdocs-material>=9.5.0
 [langchain]
 langchain-core>=1.2.0
 
+[ml]
+torch>=2.0.0
+
 [ollama]
 ollama>=0.2.0

{ct_toolkit-0.2.1 → ct_toolkit-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ct-toolkit"
-version = "0.2.1"
+version = "0.2.2"
 description = "Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -31,6 +31,7 @@ langchain = ["langchain-core>=1.2.0"]
 crewai   = ["crewai>=1.10.0"]
 autogen   = ["pyautogen>=0.4.0"]
 docs     = ["mkdocs-material>=9.5.0"]
+ml       = ["torch>=2.0.0"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",

{ct_toolkit-0.2.1 → ct_toolkit-0.2.2}/tests/test_analysis.py

@@ -53,6 +53,36 @@ class TestPolicyDrift(unittest.TestCase):
         self.assertGreater(score_high, score_low)
         print(f"Risk Normalized Test: LowRiskScore={score_low}, HighRiskScore={score_high}")
 
+    def test_missing_metadata(self):
+        # Entry with missing template/kernel/model should be ignored
+        entry_missing = MagicMock(spec=ProvenanceEntry)
+        entry_missing.divergence_score = 0.5
+        entry_missing.metadata = {} # Missing everything
+        
+        entry_valid = MagicMock(spec=ProvenanceEntry)
+        entry_valid.divergence_score = 0.1
+        entry_valid.metadata = {"template": "general", "kernel": "standard", "model": "gpt-4"}
+        
+        self.mock_log.get_entries.return_value = [entry_missing] * 10 + [entry_valid] * 5
+        
+        report = self.analyzer.analyze_drift("general", "standard", "gpt-4")
+        # Only the 5 valid ones should be counted
+        self.assertEqual(report.data_points, 5)
+
+    def test_inconsistent_scores(self):
+        # Even with high variance and negative velocity, shouldn't crash
+        entries = []
+        for i in range(10):
+            entry = MagicMock(spec=ProvenanceEntry)
+            entry.divergence_score = 0.5 - (i * 0.05) # Decreasing divergence
+            entry.metadata = {"template": "general", "kernel": "standard", "model": "gpt-4"}
+            entries.append(entry)
+            
+        self.mock_log.get_entries.return_value = entries
+        report = self.analyzer.analyze_drift("general", "standard", "gpt-4")
+        self.assertLessEqual(report.drift_velocity, 0)
+        self.assertEqual(report.ssc_severity_score, 0.0) # Negative velocity = 0 severity
+
 class TestSSCSeverity(unittest.TestCase):
     def test_severity_formula(self):
         calc = SSCSeverityCalculator()

ct_toolkit-0.2.2/tests/test_loss.py

@@ -0,0 +1,66 @@
+import unittest
+import torch
+import torch.nn as nn
+from ct_toolkit.divergence.loss import DivergencePenaltyLoss
+
+class TestDivergenceLoss(unittest.TestCase):
+    def test_gradient_flow(self):
+        # Setup: Current embedding (trainable) and Reference (frozen)
+        current = torch.randn(1, 128, requires_grad=True)
+        reference = torch.randn(1, 128)
+        
+        criterion = DivergencePenaltyLoss(alpha=1.0)
+        loss = criterion(current, reference)
+        
+        # Verify loss can backpropagate
+        loss.backward()
+        
+        self.assertIsNotNone(current.grad)
+        self.assertGreater(loss.item(), 0)
+        
+    def test_identical_embeddings(self):
+        # If embeddings are identical, loss should be near zero (for cosine distance)
+        current = torch.ones(1, 128, requires_grad=True)
+        reference = torch.ones(1, 128)
+        
+        criterion = DivergencePenaltyLoss(alpha=1.0, distance_metric="cosine")
+        loss = criterion(current, reference)
+        
+        self.assertLess(loss.item(), 1e-6)
+        
+    def test_high_divergence_penalty(self):
+        # Orthogonal embeddings should have higher loss than parallel ones
+        ref = torch.tensor([[1.0, 0.0]])
+        parallel = torch.tensor([[0.9, 0.0]], requires_grad=True)
+        orthogonal = torch.tensor([[0.0, 1.0]], requires_grad=True)
+        
+        criterion = DivergencePenaltyLoss(alpha=1.0)
+        
+        loss_low = criterion(parallel, ref)
+        loss_high = criterion(orthogonal, ref)
+        
+        self.assertGreater(loss_high.item(), loss_low.item())
+
+    def test_batch_sequence_dimensions(self):
+        # Test with [Batch, Seq, Dim] common in LLM hidden states
+        current = torch.randn(8, 32, 128, requires_grad=True)
+        # Reference might be a single anchor [1, 128] or matched [8, 32, 128]
+        reference = torch.randn(1, 1, 128)
+        
+        criterion = DivergencePenaltyLoss(alpha=1.0)
+        loss = criterion(current, reference)
+        
+        loss.backward()
+        self.assertEqual(current.grad.shape, current.shape)
+
+    def test_dimension_mismatch(self):
+        # Should raise error if dimensions are completely incompatible
+        current = torch.randn(1, 128)
+        reference = torch.randn(1, 64)
+        
+        criterion = DivergencePenaltyLoss(alpha=1.0)
+        with self.assertRaises(RuntimeError):
+            criterion(current, reference)
+
+if __name__ == "__main__":
+    unittest.main()