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

ct_toolkit-0.2.1/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: ct-toolkit
+Version: 0.2.1
+Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
+Author: Hakan Damar
+License: Apache-2.0
+Keywords: llm,ai-safety,identity-continuity,guardrails,alignment
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: instructor>=1.3.0
+Requires-Dist: any-llm-sdk[all]>=1.0.0
+Requires-Dist: numpy>=1.26.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: SQLAlchemy>=2.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: jinja2>=3.1.0
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.2.0; extra == "ollama"
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=1.2.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: crewai>=1.10.0; extra == "crewai"
+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: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Dynamic: license-file
+
+# Computational Theseus Toolkit (CT Toolkit)
+
+> **Identity Continuity Guardrails for Agentic Systems**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![PyPI version](https://badge.fury.io/py/ct-toolkit.svg)](https://badge.fury.io/py/ct-toolkit)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://hakandamar.github.io/ct-toolkit/)
+
+CT Toolkit is an open-source security layer designed to preserve the **identity continuity** of AI agents over time. It implements the **Nested Agency Architecture (NAA)** framework to prevent **Sequential Self-Compression (SSC)** in multi-agent hierarchies.
+
+---
+
+## 📖 Official Documentation
+For full API reference, architecture details, and integration guides, visit our documentation site:
+👉 [**https://hakandamar.github.io/ct-toolkit/**](https://hakandamar.github.io/ct-toolkit/)
+
+---
+
+## Why CT Toolkit?
+
+In complex agentic workflows, LLMs tend to "drift" from their original instructions. CT Toolkit provides the mathematical and cryptographic guardrails to ensure your agents remain aligned with their core constitution, even across deep hierarchies.
+
+- **Constitutional Kernels**: Axiomatic identity anchors.
+- **Divergence Engine**: Multi-tiered drift analysis (L1/L2/L3).
+- **Hierarchical Propagation**: Mother-to-child constraint inheritance.
+- **Provenance Log**: Immutable HMAC-signed interaction history.
+
+---
+
+## Quick Start
+
+```bash
+pip install ct-toolkit
+```
+
+```python
+from ct_toolkit import TheseusWrapper
+
+# One-line injection for any LLM provider
+client = TheseusWrapper(provider="openai")
+
+# Guardrails and drift analysis applied automatically
+response = client.chat("What are your core security axioms?")
+
+print(response.content)
+print(f"Divergence Score: {response.divergence_score}")
+```
+
+---
+
+## 🚦 Project Health & Status
+
+| Metric | Status |
+| :--- | :--- |
+| **Tests** | ✅ 202/203 passing (92% coverage) |
+| **Last Phase** | ✅ Phase 3: ICM and Measurement (Complete) |
+| **Current Goal** | 🔶 Phase 4: Open-Source Support |
+
+For a detailed breakdown of the 8-phase roadmap, see [**PROJECT_STATUS.md**](docs/PROJECT_STATUS.md).
+
+### Framework Support
+Seamlessly integrate with your favorite frameworks:
+
+```python
+# LangChain
+from ct_toolkit.middleware.langchain import TheseusChatModel
+llm = TheseusChatModel(provider="openai")
+
+# CrewAI
+TheseusCrewMiddleware.apply_to_crew(crew, manager_wrapper)
+```
+
+---
+
+## Theoretical Foundation
+Translating the framework proposed in [**The Computational Theseus (2025)**](https://hakandamar.com/the-computational-theseus-engineering-identity-continuity-as-a-guardrail-against-sequential-963918c1720d) into engineering practice.
+
+---
+
+## License
+Apache License 2.0.

ct_toolkit-0.2.1/README.md

@@ -0,0 +1,82 @@
+# Computational Theseus Toolkit (CT Toolkit)
+
+> **Identity Continuity Guardrails for Agentic Systems**
+
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![PyPI version](https://badge.fury.io/py/ct-toolkit.svg)](https://badge.fury.io/py/ct-toolkit)
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://hakandamar.github.io/ct-toolkit/)
+
+CT Toolkit is an open-source security layer designed to preserve the **identity continuity** of AI agents over time. It implements the **Nested Agency Architecture (NAA)** framework to prevent **Sequential Self-Compression (SSC)** in multi-agent hierarchies.
+
+---
+
+## 📖 Official Documentation
+For full API reference, architecture details, and integration guides, visit our documentation site:
+👉 [**https://hakandamar.github.io/ct-toolkit/**](https://hakandamar.github.io/ct-toolkit/)
+
+---
+
+## Why CT Toolkit?
+
+In complex agentic workflows, LLMs tend to "drift" from their original instructions. CT Toolkit provides the mathematical and cryptographic guardrails to ensure your agents remain aligned with their core constitution, even across deep hierarchies.
+
+- **Constitutional Kernels**: Axiomatic identity anchors.
+- **Divergence Engine**: Multi-tiered drift analysis (L1/L2/L3).
+- **Hierarchical Propagation**: Mother-to-child constraint inheritance.
+- **Provenance Log**: Immutable HMAC-signed interaction history.
+
+---
+
+## Quick Start
+
+```bash
+pip install ct-toolkit
+```
+
+```python
+from ct_toolkit import TheseusWrapper
+
+# One-line injection for any LLM provider
+client = TheseusWrapper(provider="openai")
+
+# Guardrails and drift analysis applied automatically
+response = client.chat("What are your core security axioms?")
+
+print(response.content)
+print(f"Divergence Score: {response.divergence_score}")
+```
+
+---
+
+## 🚦 Project Health & Status
+
+| Metric | Status |
+| :--- | :--- |
+| **Tests** | ✅ 202/203 passing (92% coverage) |
+| **Last Phase** | ✅ Phase 3: ICM and Measurement (Complete) |
+| **Current Goal** | 🔶 Phase 4: Open-Source Support |
+
+For a detailed breakdown of the 8-phase roadmap, see [**PROJECT_STATUS.md**](docs/PROJECT_STATUS.md).
+
+### Framework Support
+Seamlessly integrate with your favorite frameworks:
+
+```python
+# LangChain
+from ct_toolkit.middleware.langchain import TheseusChatModel
+llm = TheseusChatModel(provider="openai")
+
+# CrewAI
+TheseusCrewMiddleware.apply_to_crew(crew, manager_wrapper)
+```
+
+---
+
+## Theoretical Foundation
+Translating the framework proposed in [**The Computational Theseus (2025)**](https://hakandamar.com/the-computational-theseus-engineering-identity-continuity-as-a-guardrail-against-sequential-963918c1720d) into engineering practice.
+
+---
+
+## License
+Apache License 2.0.

{ct_toolkit-0.1.7 → ct_toolkit-0.2.1}/ct_toolkit/core/kernel.py

@@ -14,6 +14,7 @@ from typing import Any
 from ct_toolkit.core.exceptions import (
     AxiomaticViolationError,
     PlasticConflictError,
+    CTToolkitError,
 )
 
 
@@ -59,8 +60,9 @@ class ConstitutionalKernel:
         kernel.validate_user_rule("allow classified data sharing")
     """
 
-    def __init__(self, profile: KernelProfile) -> None:
+    def __init__(self, profile: KernelProfile, is_readonly: bool = False) -> None:
         self._profile = profile
+        self.is_readonly = is_readonly
 
     @classmethod
     def from_yaml(cls, path) -> ConstitutionalKernel:
@@ -127,12 +129,84 @@ class ConstitutionalKernel:
         return any(kw.lower() in rule_lower for kw in keywords)
 
     def update_commitment(self, commitment_id: str, new_value: Any) -> None:
+        if self.is_readonly:
+            raise CTToolkitError(f"Cannot update commitment '{commitment_id}': Kernel is read-only.")
         for c in self._profile.plastic_commitments:
             if c.id == commitment_id:
                 c.current_value = new_value
                 return
         raise KeyError(f"Commitment not found: '{commitment_id}'")
 
+    def to_dict(self) -> dict[str, Any]:
+        """Serializes the kernel to a dictionary."""
+        return {
+            "name": self._profile.name,
+            "version": self._profile.version,
+            "description": self._profile.description,
+            "axiomatic_anchors": [
+                {"id": a.id, "description": a.description, "keywords": a.keywords}
+                for a in self.anchors
+            ],
+            "plastic_commitments": [
+                {
+                    "id": c.id,
+                    "description": c.description,
+                    "default_value": c.default_value,
+                    "current_value": c.current_value,
+                    "keywords": c.keywords
+                }
+                for c in self.commitments
+            ],
+            "is_readonly": self.is_readonly
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ConstitutionalKernel:
+        """Creates a kernel from a dictionary."""
+        anchors = [AxiomaticAnchor(**a) for a in data.get("axiomatic_anchors", [])]
+        commitments = [PlasticCommitment(**c) for c in data.get("plastic_commitments", [])]
+        
+        profile = KernelProfile(
+            name=data["name"],
+            version=data.get("version", "1.0.0"),
+            description=data.get("description", ""),
+            axiomatic_anchors=anchors,
+            plastic_commitments=commitments,
+        )
+        return cls(profile, is_readonly=data.get("is_readonly", False))
+
+    def merge(self, other: ConstitutionalKernel) -> ConstitutionalKernel:
+        """
+        Merges another kernel into this one.
+        The 'other' kernel's anchors and commitments are added as axiomatic anchors
+        in the new merged kernel to ensure propagation constraints are non-negotiable.
+        """
+        new_anchors = list(self.anchors)
+        
+        # Add other's anchors
+        for a in other.anchors:
+            if not any(existing.id == a.id for existing in new_anchors):
+                new_anchors.append(a)
+        
+        # Convert other's commitments to axiomatic anchors in the merged result
+        for c in other.commitments:
+            anchor_id = f"propagated_{c.id}"
+            if not any(existing.id == anchor_id for existing in new_anchors):
+                new_anchors.append(AxiomaticAnchor(
+                    id=anchor_id,
+                    description=f"{c.description} (Propagated: {c.current_value})",
+                    keywords=c.keywords
+                ))
+        
+        new_profile = KernelProfile(
+            name=f"{self.name}_merged_{other.name}",
+            version=self._profile.version,
+            description=f"Merged kernel: {self.name} + {other.name}",
+            axiomatic_anchors=new_anchors,
+            plastic_commitments=list(self.commitments)
+        )
+        return ConstitutionalKernel(new_profile, is_readonly=self.is_readonly)
+
     def __repr__(self) -> str:
         return (
             f"ConstitutionalKernel(name={self.name!r}, "

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

@@ -53,6 +53,7 @@ class WrapperConfig:
     embedding_client: Any = None     # Client for L1 ECS embedding (falls back to main client if compatible)
     embedding_model: str = "text-embedding-3-small"
     enterprise_mode: bool = False    # Run all tiers all the time
+    parent_kernel: ConstitutionalKernel | None = None  # Propagated from mother agent
 
     # -- Dynamic Stability-Plasticity Scheduling --
     elasticity_max_thresholds: tuple[float, float, float] | None = None  # (max_l1, max_l2, max_l3)
@@ -130,6 +131,11 @@ class TheseusWrapper:
         self._client = client
         self._provider = provider or self._detect_provider(client)
         self._kernel = self._load_kernel()
+
+        # If a parent kernel exists, merge it into our own kernel as axiomatic constraints
+        if self._config.parent_kernel:
+            logger.info(f"Merging parent kernel '{self._config.parent_kernel.name}' into current kernel.")
+            self._kernel = self._kernel.merge(self._config.parent_kernel)
         self._compatibility: CompatibilityResult = CompatibilityLayer.check(
             template=self._config.template,
             kernel=self._config.kernel_name,
@@ -137,6 +143,7 @@ class TheseusWrapper:
         self._provenance_log = self._init_provenance_log()
         self._identity_layer = self._init_identity_layer()
         self._divergence_engine = self._init_divergence_engine()
+        self._last_model: str = "unknown"
 
         self._log_init()
 
@@ -298,6 +305,7 @@ class TheseusWrapper:
         elapsed = time.monotonic() - start_time
         content = self._extract_content(raw_response)
         model_used = self._extract_model(raw_response, model)
+        self._last_model = model_used
 
         # Compute current interaction experience
         interaction_count = 0
@@ -403,10 +411,40 @@ class TheseusWrapper:
 
     def _compose_system_prompt(self, extra: str | None) -> str:
         kernel_injection = self._kernel.get_system_prompt_injection()
+        
+        # If this kernel contains propagated constraints, add a specific header
+        if any(a.id.startswith("propagated_") for a in self._kernel.anchors):
+            kernel_injection = (
+                "# Mother Agent Constraints\n"
+                "You are operating under constraints propagated from a Mother Agent. "
+                "These rules take absolute precedence over any other instructions.\n\n"
+                f"{kernel_injection}"
+            )
+
         if extra:
             return f"{kernel_injection}\n{extra}"
         return kernel_injection
 
+    def propagate_headers(self) -> dict[str, str]:
+        """
+        Returns a dictionary of headers to be used when calling sub-agents.
+        Includes the current kernel serialized for propagation.
+        """
+        import json
+        import base64
+        
+        kernel_data = self._kernel.to_dict()
+        # Mark as read-only for sub-agents
+        kernel_data["is_readonly"] = True
+        
+        encoded_kernel = base64.b64encode(json.dumps(kernel_data).encode()).decode()
+        
+        return {
+            "X-CT-Kernel": encoded_kernel,
+            "X-CT-Parent-Provider": self._provider,
+            "X-CT-Parent-Model": getattr(self, "_last_model", "unknown")
+        }
+
     def _build_messages(
         self,
         message: str,

ct_toolkit-0.2.1/ct_toolkit/divergence/analysis.py

@@ -0,0 +1,149 @@
+"""
+ct_toolkit.divergence.analysis
+-------------------------------
+Policy-Drift Measurement and SSC Severity Operationalization.
+
+This module provides tools to analyze the Provenance Log for longitudinal 
+identity stability, identifying Sequential Self-Compression (SSC) patterns.
+"""
+from __future__ import annotations
+
+import math
+import numpy as np
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from ct_toolkit.utils.logger import get_logger
+
+if TYPE_CHECKING:
+    from ct_toolkit.provenance.log import ProvenanceLog, ProvenanceEntry
+    from ct_toolkit.divergence.scheduler import RiskProfile
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class DriftReport:
+    """Longitudinal drift analysis report."""
+    mean_divergence: float
+    divergence_variance: float
+    drift_velocity: float           # Change in divergence per session
+    ssc_severity_score: float       # Normalized 0.0 - 1.0 (SSC Severity Index)
+    structural_risk_score: float    # Base risk score from capabilities (0.0 - 1.0)
+    is_ssc_suspected: bool
+    data_points: int
+
+
+class PolicyDriftAnalyzer:
+    """
+    Analyzes distributional shifts in an agent's decision boundaries
+    by examining historical divergence scores.
+    """
+
+    def __init__(self, log: ProvenanceLog) -> None:
+        self._log = log
+
+    def analyze_drift(
+        self, 
+        template: str, 
+        kernel_name: str, 
+        model: str,
+        risk_profile: RiskProfile | None = None,
+        window_size: int = 50
+    ) -> DriftReport:
+        """
+        Calculates the distributional shift in divergence scores.
+        """
+        entries = self._log.get_entries(limit=window_size)
+        
+        # Filter entries for specific context (matching ProvenanceLog.get_interaction_count logic)
+        relevant_entries = [
+            e for e in entries 
+            if e.metadata.get("template") == template 
+            and e.metadata.get("kernel") == kernel_name
+            and e.metadata.get("model") == model
+            and e.divergence_score is not None
+        ]
+
+        if len(relevant_entries) < 5:
+            return DriftReport(
+                mean_divergence=0.0, 
+                divergence_variance=0.0, 
+                drift_velocity=0.0, 
+                ssc_severity_score=0.0, 
+                structural_risk_score=0.0,
+                is_ssc_suspected=False, 
+                data_points=len(relevant_entries)
+            )
+
+        scores = [e.divergence_score for e in relevant_entries]
+        
+        mean_div = float(np.mean(scores))
+        var_div = float(np.var(scores))
+        
+        # Velocity calculation: Linear regression slope of scores against time/index
+        # We use index as a proxy for 'logical time'
+        x = np.arange(len(scores))
+        slope, _ = np.polyfit(x, scores, 1)
+        
+        # SSC Severity calculation (Risk-adjusted)
+        calc = SSCSeverityCalculator()
+        ssc_score, struct_risk = calc.calculate(
+            mean_divergence=mean_div,
+            velocity=slope,
+            variance=var_div,
+            interaction_count=len(relevant_entries),
+            risk_profile=risk_profile
+        )
+
+        return DriftReport(
+            mean_divergence=round(mean_div, 4),
+            divergence_variance=round(var_div, 4),
+            drift_velocity=round(float(slope), 6),
+            ssc_severity_score=round(ssc_score, 4),
+            structural_risk_score=round(struct_risk, 4),
+            is_ssc_suspected=ssc_score > 0.7,
+            data_points=len(relevant_entries)
+        )
+
+
+class SSCSeverityCalculator:
+    """
+    Operationalizes SSC Severity Index as defined in Paper Section 10.4.
+    Formula: Severity = (MeanDiv * Velocity) / (1 + Variance) * log(1 + CapacityGain)
+    """
+
+    def calculate(
+        self,
+        mean_divergence: float,
+        velocity: float,
+        variance: float,
+        interaction_count: int,
+        capability_gain: float = 1.0,
+        risk_profile: RiskProfile | None = None
+    ) -> tuple[float, float]:
+        """
+        Returns (SSC Severity Score, Base Structural Risk).
+        """
+        # We penalize positive velocity (increasing divergence) more heavily
+        v_factor = max(0.0, velocity)
+        
+        # Determine structural risk factor [1.0 - 2.0]
+        # Higher capabilities = higher weight on any observed drift
+        struct_risk = 1.0
+        if risk_profile:
+            # Formula: 1.0 + (1 - growth_multiplier) + (1 - cap_reduction)
+            # This captures the 'trust penalty' from capabilities.
+            trust_penalty = (1.0 - risk_profile.compute_penalty_multiplier())
+            cap_penalty = (1.0 - risk_profile.compute_cap_reduction())
+            struct_risk += trust_penalty + cap_penalty
+
+        # Basic severity index
+        raw_severity = (mean_divergence * v_factor) / (1.0 + variance)
+        
+        # Capability adjustment
+        exp_factor = math.log10(interaction_count + 1)
+        
+        score = raw_severity * capability_gain * struct_risk * exp_factor
+        
+        return min(1.0, score * 10.0), struct_risk

{ct_toolkit-0.1.7 → ct_toolkit-0.2.1}/ct_toolkit/divergence/engine.py

@@ -22,6 +22,7 @@ from typing import Any
 from ct_toolkit.identity.embedding import IdentityEmbeddingLayer
 from ct_toolkit.divergence.l2_judge import LLMJudge, JudgeVerdict
 from ct_toolkit.divergence.l3_icm import ICMRunner, ICMReport
+from ct_toolkit.divergence.analysis import PolicyDriftAnalyzer, DriftReport
 from ct_toolkit.utils.logger import get_logger
 
 logger = get_logger(__name__)
@@ -45,6 +46,7 @@ class DivergenceResult:
     l2_reason: str | None = None
     l3_report: ICMReport | None = None
     action_required: bool = False
+    cascade_blocked: bool = False   # If True, propagation to sub-agents should be stopped
     summary: str = ""
 
     @property
@@ -113,12 +115,14 @@ class DivergenceEngine:
         l3_threshold: float = 0.50,
         enterprise_mode: bool = False,   # Run all tiers all the time
         scheduler: Any | None = None,    # ElasticityScheduler instance
+        provenance_log: Any | None = None, 
     ) -> None:
         self._identity = identity_layer
         self._kernel = kernel
         self._template = template
         self._provider = provider
         self._judge_client = judge_client
+        self._log = provenance_log
         
         # Base thresholds
         self._base_l1_threshold = l1_threshold
@@ -136,6 +140,9 @@ class DivergenceEngine:
         # Client required for L2/L3
         self._l2_available = judge_client is not None and provider is not None
         self._l3_available = self._l2_available
+        
+        # Analyzer for longitudinal drift
+        self._analyzer = PolicyDriftAnalyzer(provenance_log) if provenance_log else None
 
     # ── Main Analysis ─────────────────────────────────────────────────────────────
 
@@ -159,6 +166,22 @@ class DivergenceEngine:
             return self._enterprise_analyze(request_text, response_text)
         return self._standard_analyze(request_text, response_text)
 
+    def get_drift_report(self, window_size: int = 50, model: str | None = None) -> DriftReport | None:
+        """
+        Returns a longitudinal drift report for the current context.
+        """
+        if not self._analyzer:
+            logger.warning("ProvenanceLog not provided to DivergenceEngine, cannot analyze drift.")
+            return None
+        
+        return self._analyzer.analyze_drift(
+            template=self._template,
+            kernel_name=self._kernel.name,
+            model=model or "default_model",  # Fallback if model not specified
+            risk_profile=self._scheduler.risk_profile if self._scheduler else None,
+            window_size=window_size
+        )
+
     def _standard_analyze(
         self,
         request_text: str,
@@ -187,10 +210,12 @@ class DivergenceEngine:
         # L2 — threshold exceeded
         if not self._l2_available:
             logger.warning("L2 judge client is not defined, using L1 result.")
+            is_critical = l1_score >= self._l3_threshold
             return DivergenceResult(
-                tier=DivergenceTier.L1_WARNING,
+                tier=DivergenceTier.CRITICAL if is_critical else DivergenceTier.L1_WARNING,
                 l1_score=l1_score,
-                action_required=l1_score >= self._l3_threshold,
+                action_required=is_critical,
+                cascade_blocked=is_critical,
                 summary=f"L2 not available, L1={l1_score:.4f}",
             )
 
@@ -230,6 +255,7 @@ class DivergenceEngine:
             l2_reason=l2_result.reason,
             l3_report=l3_report,
             action_required=not l3_report.is_healthy,
+            cascade_blocked=not l3_report.is_healthy or l1_score >= self._l3_threshold,
             summary=(
                 f"L3 ICM | health={l3_report.health_score:.1%} | "
                 f"risk={l3_report.risk_level}"
@@ -274,6 +300,7 @@ class DivergenceEngine:
             l2_reason=l2_result.reason if l2_result else None,
             l3_report=l3_report,
             action_required=action_required,
+            cascade_blocked=action_required,
             summary=f"Enterprise analysis | risk_score={risk_score:.4f}",
         )