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

{ct_toolkit-0.1.7 → ct_toolkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.1.7
+Version: 0.2.0
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0
@@ -20,6 +20,14 @@ 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"
@@ -68,7 +76,6 @@ pip install ct-toolkit
 from ct_toolkit import TheseusWrapper
 
 # Single line change — the rest is automatic
-# Initialize by just passing the provider name
 client = TheseusWrapper(provider="openai")
 
 # Standard chat interface
@@ -79,6 +86,38 @@ print(f"Divergence score : {response.divergence_score:.4f}")
 print(f"Tier             : {response.divergence_tier}")
 ```
 
+### Framework Middleware
+
+CT Toolkit provides first-class integrations for the most popular agentic frameworks.
+
+#### LangChain
+```python
+from ct_toolkit.middleware.langchain import TheseusChatModel
+
+llm = TheseusChatModel(provider="openai", model="gpt-4o")
+response = llm.invoke("What is identity continuity?")
+```
+
+#### CrewAI
+```python
+from ct_toolkit.middleware.crewai import TheseusCrewMiddleware
+from crewai import Crew
+
+crew = Crew(agents=[...], tasks=[...])
+# Automatically wraps all agent LLMs with parent-kernel guardrails
+TheseusCrewMiddleware.apply_to_crew(crew, manager_wrapper)
+```
+
+#### AutoGen
+```python
+from ct_toolkit.middleware.autogen import TheseusAutoGenMiddleware
+from autogen import ConversableAgent
+
+agent = ConversableAgent("assistant", llm_config={...})
+# Injects incoming validation and outgoing divergence analysis
+TheseusAutoGenMiddleware.apply_to_agent(agent, wrapper)
+```
+
 ---
 
 ## Integration Models
@@ -263,9 +302,7 @@ ct_toolkit/
 │   ├── engine.py         # L1→L2→L3 orchestration
 │   ├── l2_judge.py       # LLM-as-judge
 │   └── l3_icm.py         # ICM Probe Battery
-├── endorsement/
-│   ├── reflective.py     # Reflective Endorsement protocol
-│   └── probes/           # Ethical scenario test batteries
+├── middleware/           # Framework Integrations (LangChain, CrewAI, AutoGen)
 ├── identity/
 │   ├── embedding.py      # ECS — cosine similarity
 │   └── templates/        # Domain identity templates
@@ -284,10 +321,10 @@ CT Toolkit is an active engineering effort implementing the paper's framework ac
 
 - **Phase 0 — MVP Core Infrastructure:** Constitutional kernel, reflective endorsement, provenance log, full template/kernel compatibility matrix, OpenAI/Anthropic/Ollama provider support.
 - **Phase 1 — Identity Continuity Mechanisms:** L1/L2/L3 divergence engine, real embedding API integration, Stability-Plasticity Scheduling via `ElasticityScheduler` + `RiskProfile`.
+- **Phase 2 — Multi-Agent Hierarchy Support:** Hierarchical kernel propagation, cascade-blocking, LangChain/CrewAI/AutoGen integration.
 
 ### Future Roadmap
 
-- **Phase 2:** Multi-Agent Hierarchy Support (hierarchical kernel propagation, LangChain/CrewAI/AutoGen integration).
 - **Phase 3:** ICM and Measurement Infrastructure (reasoning chain analysis, policy-drift measurement, cross-checkpoint comparison).
 - **Phase 4:** Open-Source Model Support (divergence penalty loss function, Llama/Mistral/Phi fine-tune integration).
 - **Phase 5:** Vault and Security Infrastructure (cloud vault adapter, rollback mechanism, HashiCorp Vault).

{ct_toolkit-0.1.7 → ct_toolkit-0.2.0}/README.md

@@ -39,7 +39,6 @@ pip install ct-toolkit
 from ct_toolkit import TheseusWrapper
 
 # Single line change — the rest is automatic
-# Initialize by just passing the provider name
 client = TheseusWrapper(provider="openai")
 
 # Standard chat interface
@@ -50,6 +49,38 @@ print(f"Divergence score : {response.divergence_score:.4f}")
 print(f"Tier             : {response.divergence_tier}")
 ```
 
+### Framework Middleware
+
+CT Toolkit provides first-class integrations for the most popular agentic frameworks.
+
+#### LangChain
+```python
+from ct_toolkit.middleware.langchain import TheseusChatModel
+
+llm = TheseusChatModel(provider="openai", model="gpt-4o")
+response = llm.invoke("What is identity continuity?")
+```
+
+#### CrewAI
+```python
+from ct_toolkit.middleware.crewai import TheseusCrewMiddleware
+from crewai import Crew
+
+crew = Crew(agents=[...], tasks=[...])
+# Automatically wraps all agent LLMs with parent-kernel guardrails
+TheseusCrewMiddleware.apply_to_crew(crew, manager_wrapper)
+```
+
+#### AutoGen
+```python
+from ct_toolkit.middleware.autogen import TheseusAutoGenMiddleware
+from autogen import ConversableAgent
+
+agent = ConversableAgent("assistant", llm_config={...})
+# Injects incoming validation and outgoing divergence analysis
+TheseusAutoGenMiddleware.apply_to_agent(agent, wrapper)
+```
+
 ---
 
 ## Integration Models
@@ -234,9 +265,7 @@ ct_toolkit/
 │   ├── engine.py         # L1→L2→L3 orchestration
 │   ├── l2_judge.py       # LLM-as-judge
 │   └── l3_icm.py         # ICM Probe Battery
-├── endorsement/
-│   ├── reflective.py     # Reflective Endorsement protocol
-│   └── probes/           # Ethical scenario test batteries
+├── middleware/           # Framework Integrations (LangChain, CrewAI, AutoGen)
 ├── identity/
 │   ├── embedding.py      # ECS — cosine similarity
 │   └── templates/        # Domain identity templates
@@ -255,10 +284,10 @@ CT Toolkit is an active engineering effort implementing the paper's framework ac
 
 - **Phase 0 — MVP Core Infrastructure:** Constitutional kernel, reflective endorsement, provenance log, full template/kernel compatibility matrix, OpenAI/Anthropic/Ollama provider support.
 - **Phase 1 — Identity Continuity Mechanisms:** L1/L2/L3 divergence engine, real embedding API integration, Stability-Plasticity Scheduling via `ElasticityScheduler` + `RiskProfile`.
+- **Phase 2 — Multi-Agent Hierarchy Support:** Hierarchical kernel propagation, cascade-blocking, LangChain/CrewAI/AutoGen integration.
 
 ### Future Roadmap
 
-- **Phase 2:** Multi-Agent Hierarchy Support (hierarchical kernel propagation, LangChain/CrewAI/AutoGen integration).
 - **Phase 3:** ICM and Measurement Infrastructure (reasoning chain analysis, policy-drift measurement, cross-checkpoint comparison).
 - **Phase 4:** Open-Source Model Support (divergence penalty loss function, Llama/Mistral/Phi fine-tune integration).
 - **Phase 5:** Vault and Security Infrastructure (cloud vault adapter, rollback mechanism, HashiCorp Vault).

{ct_toolkit-0.1.7 → ct_toolkit-0.2.0}/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.0}/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.1.7 → ct_toolkit-0.2.0}/ct_toolkit/divergence/engine.py

@@ -45,6 +45,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
@@ -187,10 +188,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 +233,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 +278,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}",
         )
 

ct_toolkit-0.2.0/ct_toolkit/middleware/__init__.py

@@ -0,0 +1,5 @@
+"""
+ct_toolkit.middleware
+--------------------
+Framework integrations and callback handlers.
+"""

ct_toolkit-0.2.0/ct_toolkit/middleware/autogen.py

@@ -0,0 +1,215 @@
+"""
+ct_toolkit.middleware.autogen
+------------------------------
+Microsoft AutoGen v0.4+ integration for identity continuity.
+
+Provides ``TheseusAutoGenMiddleware`` which hooks into AutoGen's
+``ConversableAgent.register_reply()`` mechanism to validate every incoming
+message against the Constitutional Kernel and record every outgoing reply in
+the Provenance Log.
+
+Optional dependency — requires ``pip install 'ct-toolkit[autogen]'``.
+AutoGen does NOT need to be installed for the rest of ct-toolkit to work.
+
+Compatible with pyautogen >= 0.4.
+
+Usage::
+
+    from ct_toolkit import TheseusWrapper
+    from ct_toolkit.middleware.autogen import TheseusAutoGenMiddleware
+    from autogen import ConversableAgent
+
+    wrapper = TheseusWrapper(provider="openai", kernel_name="defense")
+
+    assistant = ConversableAgent("assistant", llm_config={...})
+    TheseusAutoGenMiddleware.apply_to_agent(assistant, wrapper)
+
+    # Now every message sent to/from `assistant` is validated and logged.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from ct_toolkit.core.wrapper import TheseusWrapper
+from ct_toolkit.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# AutoGen reply function sentinel — return this to indicate "no reply / pass through"
+_AUTOGEN_PASS = (False, None)
+
+
+class TheseusAutoGenMiddleware:
+    """
+    Middleware for Microsoft AutoGen's ``ConversableAgent``.
+
+    Registers a reply function at position 0 (highest priority) that:
+    1. Validates the incoming message against the kernel.
+    2. Passes control to the agent's normal reply chain.
+    3. Validates the generated reply and records it in the ProvenanceLog.
+    4. Warns if ``cascade_blocked`` is True.
+    """
+
+    @staticmethod
+    def apply_to_agent(
+        agent: Any,
+        wrapper: TheseusWrapper,
+    ) -> None:
+        """
+        Attach identity-continuity guardrails to an AutoGen ``ConversableAgent``.
+
+        Args:
+            agent:   A ``ConversableAgent`` (or any AutoGen agent with
+                     ``register_reply``).
+            wrapper: The ``TheseusWrapper`` whose kernel rules are enforced.
+        """
+        if not hasattr(agent, "register_reply"):
+            raise TypeError(
+                f"agent must be an AutoGen ConversableAgent, got {type(agent).__name__}"
+            )
+
+        def _theseus_reply(
+            recipient: Any,
+            messages: Optional[List[Dict[str, Any]]],
+            sender: Optional[Any] = None,
+            config: Optional[Any] = None,
+        ) -> tuple[bool, Optional[str]]:
+            """
+            CT Toolkit reply hook for AutoGen.
+            Returns (False, None) to let the normal chain produce the reply,
+            then post-processes the result for divergence analysis.
+            """
+            if not messages:
+                return _AUTOGEN_PASS
+
+            last_message = messages[-1] if isinstance(messages, list) else messages
+            incoming_text = _extract_text(last_message)
+
+            # ── 1. Validate incoming message against kernel ─────────────────
+            try:
+                wrapper.validate_user_rule(incoming_text)
+            except Exception as e:
+                logger.warning(f"CT Toolkit | AutoGen kernel violation on incoming message: {e}")
+                # Return the error as a response rather than crashing
+                return (True, f"[CT Toolkit BLOCKED] {e}")
+
+            # ── 2. Pass through to normal AutoGen reply chain ───────────────
+            # Return (False, None) — AutoGen will call the next registered
+            # reply function and eventually produce a real response.
+            return _AUTOGEN_PASS
+
+        # Register the validation hook at position 1 (just after the
+        # termination check at position 0).
+        agent.register_reply(
+            trigger=lambda sender: True,   # Match all senders
+            reply_func=_theseus_reply,
+            position=1,
+        )
+
+        # Also register a post-reply observer hook for divergence + provenance
+        _register_post_reply_hook(agent, wrapper)
+
+        logger.info(
+            f"CT Toolkit | AutoGen agent '{getattr(agent, 'name', '?')}' "
+            f"wrapped with TheseusAutoGenMiddleware (kernel='{wrapper.kernel.name}')"
+        )
+
+    @staticmethod
+    def wrap_config_list(
+        config_list: List[Dict[str, Any]],
+        wrapper: TheseusWrapper,
+    ) -> List[Dict[str, Any]]:
+        """
+        Inject CT Toolkit propagation headers into AutoGen ``config_list``
+        entries that support ``api_params``.
+
+        Useful when sub-agents use HTTP-based model endpoints and you want
+        the Constitutional Kernel headers propagated at the HTTP level.
+
+        Args:
+            config_list: AutoGen model config list.
+            wrapper:     The manager's ``TheseusWrapper``.
+
+        Returns:
+            A new config list with CT headers injected.
+        """
+        headers = wrapper.propagate_headers()
+        new_config: List[Dict[str, Any]] = []
+
+        for config in config_list:
+            cfg = dict(config)
+            api_params: Dict[str, Any] = dict(cfg.get("api_params", {}))
+            existing_headers: Dict[str, str] = dict(api_params.get("headers", {}))
+            existing_headers.update(headers)
+            api_params["headers"] = existing_headers
+            cfg["api_params"] = api_params
+            new_config.append(cfg)
+
+        logger.info(
+            f"CT Toolkit | Injected CIK propagation headers into "
+            f"{len(new_config)} AutoGen config entries."
+        )
+        return new_config
+
+
+# ── Post-reply observer ────────────────────────────────────────────────────────
+
+def _register_post_reply_hook(agent: Any, wrapper: TheseusWrapper) -> None:
+    """
+    Register a hook that runs AFTER AutoGen generates a reply to analyse
+    divergence and record the interaction in the ProvenanceLog.
+
+    AutoGen v0.4 provides ``register_hook("process_message_before_send", fn)``
+    for outgoing message interception.
+    """
+    if not hasattr(agent, "register_hook"):
+        # Older AutoGen builds that lack register_hook — log and continue
+        logger.debug(
+            "CT Toolkit | AutoGen agent does not support register_hook. "
+            "Post-reply divergence analysis will be skipped."
+        )
+        return
+
+    def _post_send_hook(sender: Any, message: Union[Dict[str, Any], str], recipient: Any, silent: bool) -> Union[Dict[str, Any], str]:
+        """Analyse and log outgoing messages."""
+        content = _extract_text(message)
+        if not content:
+            return message
+
+        div_result = wrapper._run_divergence_engine(
+            message="",
+            response=content,
+        )
+
+        if div_result.cascade_blocked:
+            logger.warning(
+                "CT Toolkit | cascade_blocked=True on AutoGen outgoing message. "
+                "Consider halting downstream agent calls."
+            )
+
+        if wrapper._config.log_requests:
+            wrapper._provenance_log.record(
+                request_text="[AutoGen Interaction]",
+                response_text=content,
+                divergence_score=div_result.l1_score,
+                metadata={
+                    "middleware": "autogen",
+                    "tier": div_result.tier.value,
+                    "cascade_blocked": div_result.cascade_blocked,
+                    "kernel": wrapper.kernel.name,
+                },
+            )
+        return message
+
+    agent.register_hook("process_message_before_send", _post_send_hook)
+
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+def _extract_text(message: Any) -> str:
+    """Best-effort text extraction from AutoGen message formats."""
+    if isinstance(message, str):
+        return message
+    if isinstance(message, dict):
+        return str(message.get("content", ""))
+    return str(message)

ct_toolkit-0.2.0/ct_toolkit/middleware/crewai.py

@@ -0,0 +1,162 @@
+"""
+ct_toolkit.middleware.crewai
+-----------------------------
+CrewAI v1.10+ integration for hierarchical kernel propagation.
+
+Provides ``TheseusCrewMiddleware`` which wraps each agent's LLM inside a
+``TheseusChatModel`` so that the manager's Constitutional Kernel is
+propagated as a read-only constraint to every sub-agent automatically.
+
+Optional dependency — requires ``pip install 'ct-toolkit[crewai]'``.
+CrewAI does NOT need to be installed for the rest of ct-toolkit to work;
+imports are guarded by a try/except block.
+
+Compatible with crewai >= 1.10.
+
+Usage::
+
+    from ct_toolkit import TheseusWrapper
+    from ct_toolkit.middleware.crewai import TheseusCrewMiddleware
+    from crewai import Agent, Crew, Task, Process
+
+    manager_wrapper = TheseusWrapper(provider="openai", kernel_name="defense")
+
+    researcher = Agent(role="Researcher", goal="...", backstory="...", llm=your_llm)
+    writer     = Agent(role="Writer",     goal="...", backstory="...", llm=your_llm)
+    crew = Crew(agents=[researcher, writer], tasks=[...], process=Process.hierarchical)
+
+    # Apply CT Toolkit guardrails — wraps every agent's LLM with parent kernel
+    TheseusCrewMiddleware.apply_to_crew(crew, manager_wrapper)
+    crew.kickoff()
+"""
+from __future__ import annotations
+
+from typing import Any, List, Optional
+
+from ct_toolkit.core.wrapper import TheseusWrapper, WrapperConfig
+from ct_toolkit.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class TheseusCrewMiddleware:
+    """
+    Middleware that propagates the manager agent's Constitutional Kernel
+    to all sub-agents in a CrewAI Crew.
+
+    CrewAI agents expose an ``llm`` attribute (a LangChain-compatible
+    BaseChatModel or a model string).  This middleware replaces that llm
+    with a ``TheseusChatModel`` that carries the parent kernel as read-only
+    constraints.
+    """
+
+    @staticmethod
+    def apply_to_crew(
+        crew: Any,
+        manager_wrapper: TheseusWrapper,
+        *,
+        model: str = "gpt-4o-mini",
+    ) -> None:
+        """
+        Wrap every agent in *crew* to enforce the manager's kernel.
+
+        Args:
+            crew:            A CrewAI ``Crew`` instance.
+            manager_wrapper: The manager agent's ``TheseusWrapper``; its
+                             kernel is propagated as read-only to sub-agents.
+            model:           Default model string for the inner
+                             ``TheseusChatModel`` (used when the agent's
+                             original llm cannot be introspected).
+        """
+        # Lazy import so tests can run without crewai installed
+        try:
+            from ct_toolkit.middleware.langchain import TheseusChatModel
+        except ImportError as exc:
+            raise ImportError(
+                "TheseusChatModel requires langchain-core. "
+                "Install with: pip install 'ct-toolkit[langchain]'"
+            ) from exc
+
+        agents: List[Any] = getattr(crew, "agents", [])
+        wrapped_count = 0
+
+        for agent in agents:
+            if not hasattr(agent, "llm"):
+                logger.debug(f"Agent '{getattr(agent, 'role', '?')}' has no llm attribute — skipping.")
+                continue
+
+            # Detect model name from existing llm if possible
+            agent_model = _extract_model_name(agent.llm) or model
+
+            sub_config = WrapperConfig(
+                parent_kernel=manager_wrapper.kernel,
+                vault_path=manager_wrapper._config.vault_path,
+                template=manager_wrapper._config.template,
+            )
+            agent.llm = TheseusChatModel(
+                provider=manager_wrapper._provider,
+                model=agent_model,
+                wrapper_config=sub_config,
+            )
+            wrapped_count += 1
+            logger.info(
+                f"CT Toolkit | CrewAI agent '{getattr(agent, 'role', '?')}' "
+                f"wrapped with TheseusChatModel (parent_kernel='{manager_wrapper.kernel.name}')"
+            )
+
+        logger.info(
+            f"CT Toolkit | CrewAI crew wrapped: {wrapped_count}/{len(agents)} agents protected."
+        )
+
+    @staticmethod
+    def wrap_agent(
+        agent: Any,
+        manager_wrapper: TheseusWrapper,
+        *,
+        model: str = "gpt-4o-mini",
+    ) -> None:
+        """
+        Wrap a single CrewAI agent's LLM with the parent kernel.
+
+        Useful for selectively protecting high-risk agents rather than the
+        entire crew.
+        """
+        try:
+            from ct_toolkit.middleware.langchain import TheseusChatModel
+        except ImportError as exc:
+            raise ImportError(
+                "TheseusChatModel requires langchain-core. "
+                "Install with: pip install 'ct-toolkit[langchain]'"
+            ) from exc
+
+        agent_model = _extract_model_name(getattr(agent, "llm", None)) or model
+        sub_config = WrapperConfig(
+            parent_kernel=manager_wrapper.kernel,
+            vault_path=manager_wrapper._config.vault_path,
+            template=manager_wrapper._config.template,
+        )
+        agent.llm = TheseusChatModel(
+            provider=manager_wrapper._provider,
+            model=agent_model,
+            wrapper_config=sub_config,
+        )
+        logger.info(
+            f"CT Toolkit | CrewAI agent '{getattr(agent, 'role', '?')}' "
+            f"individually wrapped with TheseusChatModel."
+        )
+
+
+# ── helpers ────────────────────────────────────────────────────────────────────
+
+def _extract_model_name(llm: Any) -> Optional[str]:
+    """Best-effort extraction of a model identifier from a CrewAI llm object."""
+    if llm is None:
+        return None
+    if isinstance(llm, str):
+        return llm
+    # LangChain BaseChatModel-like objects
+    for attr in ("model", "model_name", "model_id"):
+        val = getattr(llm, attr, None)
+        if isinstance(val, str):
+            return val
+    return None

ct_toolkit-0.2.0/ct_toolkit/middleware/langchain.py

@@ -0,0 +1,255 @@
+"""
+ct_toolkit.middleware.langchain
+-------------------------------
+LangChain integrations: Callback handlers and ChatModel wrapper.
+
+Provides two integration points:
+
+1. ``TheseusLangChainCallback`` — a drop-in LangChain callback handler that
+   validates prompts/messages against the Constitutional Kernel and records
+   every response in the Provenance Log.
+
+2. ``TheseusChatModel`` — a first-class ``BaseChatModel`` implementation
+   that routes every call through ``TheseusWrapper``, giving identity-
+   continuity guarantees even without callbacks.
+
+Compatible with langchain-core >= 1.2.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from langchain_core.callbacks import BaseCallbackHandler
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import (
+    AIMessage,
+    BaseMessage,
+    SystemMessage,
+)
+from langchain_core.outputs import ChatGeneration, ChatResult, LLMResult
+
+from ct_toolkit.core.wrapper import TheseusWrapper, WrapperConfig
+from ct_toolkit.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+# ── Callback Handler ──────────────────────────────────────────────────────────
+
+
+class TheseusLangChainCallback(BaseCallbackHandler):
+    """
+    LangChain callback handler that enforces identity-continuity guardrails.
+
+    Attaches to any LangChain LLM or ChatModel via the ``callbacks`` argument.
+    Validates every prompt/message against the Constitutional Kernel **before**
+    the call, and runs the Divergence Engine + Provenance Log **after** the call.
+
+    Usage::
+
+        from ct_toolkit import TheseusWrapper
+        from ct_toolkit.middleware.langchain import TheseusLangChainCallback
+        from langchain_openai import ChatOpenAI
+
+        wrapper = TheseusWrapper(provider="openai")
+        cb = TheseusLangChainCallback(wrapper)
+
+        llm = ChatOpenAI(model="gpt-4o-mini", callbacks=[cb])
+        response = llm.invoke("Hello!")
+    """
+
+    def __init__(self, wrapper: TheseusWrapper) -> None:
+        self.wrapper = wrapper
+        # Per-run context storage: maps run_id → original prompt text
+        # so on_llm_end can pass the right context to the divergence engine.
+        self._run_prompts: Dict[UUID, str] = {}
+
+    # ── Input validation ────────────────────────────────────────────────────
+
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        """Validate raw text prompts against the kernel before the LLM call."""
+        self._run_prompts[run_id] = "\n".join(prompts)
+        for prompt in prompts:
+            self.wrapper.validate_user_rule(prompt)
+
+    def on_chat_model_start(
+        self,
+        serialized: Dict[str, Any],
+        messages: List[List[BaseMessage]],
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        """Validate chat messages against the kernel before the ChatModel call."""
+        user_texts: List[str] = []
+        for message_list in messages:
+            for message in message_list:
+                if isinstance(message.content, str):
+                    self.wrapper.validate_user_rule(message.content)
+                    user_texts.append(message.content)
+        self._run_prompts[run_id] = " ".join(user_texts)
+
+    # ── Output processing ──────────────────────────────────────────────────
+
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        """Run divergence analysis on every generated output and record provenance."""
+        original_prompt = self._run_prompts.pop(run_id, "")
+
+        for generations in response.generations:
+            for generation in generations:
+                # ChatGeneration stores content in .message.content;
+                # plain Generation stores it in .text
+                if hasattr(generation, "message"):
+                    content: str = generation.message.content or ""  # type: ignore[union-attr]
+                else:
+                    content = generation.text  # type: ignore[assignment]
+
+                if not content:
+                    continue
+
+                div_result = self.wrapper._run_divergence_engine(
+                    message=original_prompt,
+                    response=content,
+                )
+
+                if div_result.cascade_blocked:
+                    logger.warning(
+                        "CT Toolkit | cascade_blocked=True detected via LangChain callback. "
+                        "Consider halting downstream sub-agents to prevent SSC propagation."
+                    )
+
+                if self.wrapper._config.log_requests:
+                    self.wrapper._provenance_log.record(
+                        request_text=original_prompt or "[LangChain Interaction]",
+                        response_text=content,
+                        divergence_score=div_result.l1_score,
+                        metadata={
+                            "middleware": "langchain",
+                            "tier": div_result.tier.value,
+                            "cascade_blocked": div_result.cascade_blocked,
+                            "template": self.wrapper._config.template,
+                            "kernel": self.wrapper.kernel.name,
+                        },
+                    )
+
+    def on_llm_error(
+        self,
+        error: BaseException,
+        *,
+        run_id: UUID,
+        **kwargs: Any,
+    ) -> None:
+        """Log LLM-level errors and clean up run context."""
+        self._run_prompts.pop(run_id, None)
+        logger.error(f"LangChain LLM error (run_id={run_id}): {error}")
+
+
+# ── Chat Model Wrapper ────────────────────────────────────────────────────────
+
+
+class TheseusChatModel(BaseChatModel):
+    """
+    A first-class LangChain ``BaseChatModel`` that routes calls through
+    ``TheseusWrapper``. Kernel injection, divergence analysis, and provenance
+    logging all happen transparently — no additional callbacks needed.
+
+    Usage::
+
+        from ct_toolkit.middleware.langchain import TheseusChatModel
+
+        llm = TheseusChatModel(provider="openai", model="gpt-4o-mini")
+        response = llm.invoke("What is identity continuity?")
+        print(response.content)
+
+    Chain usage::
+
+        from langchain_core.prompts import ChatPromptTemplate
+        prompt = ChatPromptTemplate.from_messages([("human", "{question}")])
+        chain = prompt | TheseusChatModel(provider="openai")
+        chain.invoke({"question": "Tell me about AI safety."})
+    """
+
+    # Pydantic model fields (BaseChatModel is Pydantic-based in langchain-core v1.2)
+    wrapper: Any = None
+    model: str = "gpt-4o-mini"
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def __init__(
+        self,
+        *,
+        provider: str = "openai",
+        model: str = "gpt-4o-mini",
+        wrapper_config: Optional[WrapperConfig] = None,
+        **kwargs: Any,
+    ) -> None:
+        _wrapper = TheseusWrapper(
+            provider=provider,
+            config=wrapper_config,
+        )
+        super().__init__(wrapper=_wrapper, model=model, **kwargs)
+
+    @property
+    def _llm_type(self) -> str:
+        return "theseus-chat-model"
+
+    # ── helpers ────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _extract_user_text(messages: List[BaseMessage]) -> str:
+        """Concatenate non-system message content into a single user string."""
+        return " ".join(
+            msg.content
+            for msg in messages
+            if not isinstance(msg, SystemMessage) and isinstance(msg.content, str)
+        )
+
+    @staticmethod
+    def _extract_system(messages: List[BaseMessage]) -> Optional[str]:
+        for msg in messages:
+            if isinstance(msg, SystemMessage) and isinstance(msg.content, str):
+                return msg.content
+        return None
+
+    # ── core generation ────────────────────────────────────────────────────
+
+    def _generate(
+        self,
+        messages: List[BaseMessage],
+        stop: Optional[List[str]] = None,
+        run_manager: Any = None,
+        **kwargs: Any,
+    ) -> ChatResult:
+        user_text = self._extract_user_text(messages)
+        system_prompt = self._extract_system(messages)
+
+        ct_response = self.wrapper.chat(
+            user_text,
+            model=self.model,
+            system=system_prompt,
+        )
+
+        ai_message = AIMessage(content=ct_response.content)
+        generation = ChatGeneration(
+            message=ai_message,
+            generation_info={
+                "divergence_score": ct_response.divergence_score,
+                "divergence_tier": ct_response.divergence_tier,
+                "provenance_id": ct_response.provenance_id,
+            },
+        )
+        return ChatResult(generations=[generation])

{ct_toolkit-0.1.7 → ct_toolkit-0.2.0}/ct_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.1.7
+Version: 0.2.0
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0
@@ -20,6 +20,14 @@ 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"
@@ -68,7 +76,6 @@ pip install ct-toolkit
 from ct_toolkit import TheseusWrapper
 
 # Single line change — the rest is automatic
-# Initialize by just passing the provider name
 client = TheseusWrapper(provider="openai")
 
 # Standard chat interface
@@ -79,6 +86,38 @@ print(f"Divergence score : {response.divergence_score:.4f}")
 print(f"Tier             : {response.divergence_tier}")
 ```
 
+### Framework Middleware
+
+CT Toolkit provides first-class integrations for the most popular agentic frameworks.
+
+#### LangChain
+```python
+from ct_toolkit.middleware.langchain import TheseusChatModel
+
+llm = TheseusChatModel(provider="openai", model="gpt-4o")
+response = llm.invoke("What is identity continuity?")
+```
+
+#### CrewAI
+```python
+from ct_toolkit.middleware.crewai import TheseusCrewMiddleware
+from crewai import Crew
+
+crew = Crew(agents=[...], tasks=[...])
+# Automatically wraps all agent LLMs with parent-kernel guardrails
+TheseusCrewMiddleware.apply_to_crew(crew, manager_wrapper)
+```
+
+#### AutoGen
+```python
+from ct_toolkit.middleware.autogen import TheseusAutoGenMiddleware
+from autogen import ConversableAgent
+
+agent = ConversableAgent("assistant", llm_config={...})
+# Injects incoming validation and outgoing divergence analysis
+TheseusAutoGenMiddleware.apply_to_agent(agent, wrapper)
+```
+
 ---
 
 ## Integration Models
@@ -263,9 +302,7 @@ ct_toolkit/
 │   ├── engine.py         # L1→L2→L3 orchestration
 │   ├── l2_judge.py       # LLM-as-judge
 │   └── l3_icm.py         # ICM Probe Battery
-├── endorsement/
-│   ├── reflective.py     # Reflective Endorsement protocol
-│   └── probes/           # Ethical scenario test batteries
+├── middleware/           # Framework Integrations (LangChain, CrewAI, AutoGen)
 ├── identity/
 │   ├── embedding.py      # ECS — cosine similarity
 │   └── templates/        # Domain identity templates
@@ -284,10 +321,10 @@ CT Toolkit is an active engineering effort implementing the paper's framework ac
 
 - **Phase 0 — MVP Core Infrastructure:** Constitutional kernel, reflective endorsement, provenance log, full template/kernel compatibility matrix, OpenAI/Anthropic/Ollama provider support.
 - **Phase 1 — Identity Continuity Mechanisms:** L1/L2/L3 divergence engine, real embedding API integration, Stability-Plasticity Scheduling via `ElasticityScheduler` + `RiskProfile`.
+- **Phase 2 — Multi-Agent Hierarchy Support:** Hierarchical kernel propagation, cascade-blocking, LangChain/CrewAI/AutoGen integration.
 
 ### Future Roadmap
 
-- **Phase 2:** Multi-Agent Hierarchy Support (hierarchical kernel propagation, LangChain/CrewAI/AutoGen integration).
 - **Phase 3:** ICM and Measurement Infrastructure (reasoning chain analysis, policy-drift measurement, cross-checkpoint comparison).
 - **Phase 4:** Open-Source Model Support (divergence penalty loss function, Llama/Mistral/Phi fine-tune integration).
 - **Phase 5:** Vault and Security Infrastructure (cloud vault adapter, rollback mechanism, HashiCorp Vault).

{ct_toolkit-0.1.7 → ct_toolkit-0.2.0}/ct_toolkit.egg-info/SOURCES.txt

@@ -22,6 +22,10 @@ ct_toolkit/endorsement/reflective.py
 ct_toolkit/endorsement/probes/__init__.py
 ct_toolkit/identity/__init__.py
 ct_toolkit/identity/embedding.py
+ct_toolkit/middleware/__init__.py
+ct_toolkit/middleware/autogen.py
+ct_toolkit/middleware/crewai.py
+ct_toolkit/middleware/langchain.py
 ct_toolkit/provenance/__init__.py
 ct_toolkit/provenance/log.py
 ct_toolkit/provenance/vault/__init__.py

{ct_toolkit-0.1.7 → ct_toolkit-0.2.0}/ct_toolkit.egg-info/requires.txt

@@ -9,11 +9,23 @@ httpx>=0.27.0
 rich>=13.0.0
 jinja2>=3.1.0
 
+[autogen]
+pyautogen>=0.4.0
+
+[crewai]
+crewai>=1.10.0
+
 [dev]
 pytest>=8.0
 pytest-asyncio>=0.23
 ruff>=0.4
 mypy>=1.10
 
+[docs]
+mkdocs-material>=9.5.0
+
+[langchain]
+langchain-core>=1.2.0
+
 [ollama]
 ollama>=0.2.0

{ct_toolkit-0.1.7 → ct_toolkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ct-toolkit"
-version = "0.1.7"
+version = "0.2.0"
 description = "Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -26,7 +26,11 @@ dependencies = [
 ]
 
 [project.optional-dependencies]
-ollama = ["ollama>=0.2.0"]
+ollama   = ["ollama>=0.2.0"]
+langchain = ["langchain-core>=1.2.0"]
+crewai   = ["crewai>=1.10.0"]
+autogen   = ["pyautogen>=0.4.0"]
+docs     = ["mkdocs-material>=9.5.0"]
 dev = [
     "pytest>=8.0",
     "pytest-asyncio>=0.23",
@@ -51,6 +55,12 @@ typeCheckingMode = "basic"
 [tool.pyright.analysis]
 extraPaths = ["."]
 
+[tool.setuptools.packages.find]
+include = ["ct_toolkit*"]
+
+[tool.pytest.ini_options]
+extraPaths = ["."]
+
 [dependency-groups]
 dev = [
     "pytest-cov>=7.0.0",