ct-toolkit 0.3.20__tar.gz → 0.3.22__tar.gz

{ct_toolkit-0.3.20 → ct_toolkit-0.3.22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.3.20
+Version: 0.3.22
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0
@@ -50,6 +50,7 @@ Dynamic: license-file
 [![PyPI version](https://img.shields.io/pypi/v/ct-toolkit.svg)](https://pypi.org/project/ct-toolkit/)
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://hakandamar.github.io/ct-toolkit/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/ct-toolkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=MAGENTA&left_text=downloads)](https://pepy.tech/projects/ct-toolkit)
+[![codecov](https://codecov.io/gh/hakandamar/ct-toolkit/graph/badge.svg?token=2OTO27N02C)](https://codecov.io/gh/hakandamar/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 Agentic Architecture (NAA)** framework to prevent **Sequential Self-Compression (SSC)** in multi-agent hierarchies.
 
@@ -62,6 +63,7 @@ For full API reference, architecture details, examples, and integration guides,
 
 - [**Live Examples & Case Studies**](https://hakandamar.github.io/ct-toolkit/examples/): Real-world scenarios like Financial Auditor Integrity.
 - [**FastAPI Integration Test Project**](https://github.com/hakandamar/ct-toolkit-fastapi): Reference FastAPI app for validating CT Toolkit end-to-end across L1/L2/L3 guardrails and provenance logs with local model infrastructure.
+- [**Deep Agents Integration Test Project**](https://github.com/hakandamar/ct-toolkit-deep-agents): Reference Deep Agents app for validating CT Toolkit end-to-end with hierarchical agent workflows, L1/L2/L3 guardrails, and provenance logs.
 
 ---
 
@@ -117,16 +119,18 @@ ct-toolkit list-templates
 
 If you want a runnable application example instead of a CLI-only flow, see [**ct-toolkit-fastapi**](https://github.com/hakandamar/ct-toolkit-fastapi), a small FastAPI validation project that developers can use to test CT Toolkit locally with automated endpoints and pytest coverage.
 
+For Deep Agents workflows, see [**ct-toolkit-deep-agents**](https://github.com/hakandamar/ct-toolkit-deep-agents), a reference integration project for validating CT Toolkit in multi-agent orchestration scenarios.
+
 ---
 
 ## 🚦 Project Health & Status
 
-| Metric           | Status                                                  |
-| :--------------- | :------------------------------------------------------ |
-| **Tests**        | ✅ 330 passed, 0 failed (100% success rate, 93% coverage)                       |
+| Metric           | Status                                                                                                                                                                                                              |
+| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Tests**        | ✅ 397 passed, 3 skipped (100% success rate, 90% coverage)                                                                                                                                                           |
 | **Downloads**    | [![PyPI Downloads](https://static.pepy.tech/personalized-badge/ct-toolkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=MAGENTA&left_text=downloads)](https://pepy.tech/projects/ct-toolkit) |
-| **Last Phase**   | ✅ v0.3.20: Capability registry + role/environment policy metadata standardized across middleware  |
-| **Current Goal** | 🔶 Phase 7: Multi-Agent Synchronization (Integration)   |
+| **Last Phase**   | ✅ v0.3.22: CI/CD pipeline fix — Proper dependency installation via `uv sync --all-extras --dev` in GitHub Actions                                                                                                   |
+| **Current Goal** | 🔶 Phase 7: Multi-Agent Synchronization (Integration)                                                                                                                                                               |
 
 ### Framework & Model Support
 

{ct_toolkit-0.3.20 → ct_toolkit-0.3.22}/README.md

@@ -7,6 +7,7 @@
 [![PyPI version](https://img.shields.io/pypi/v/ct-toolkit.svg)](https://pypi.org/project/ct-toolkit/)
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://hakandamar.github.io/ct-toolkit/)
 [![PyPI Downloads](https://static.pepy.tech/personalized-badge/ct-toolkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=MAGENTA&left_text=downloads)](https://pepy.tech/projects/ct-toolkit)
+[![codecov](https://codecov.io/gh/hakandamar/ct-toolkit/graph/badge.svg?token=2OTO27N02C)](https://codecov.io/gh/hakandamar/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 Agentic Architecture (NAA)** framework to prevent **Sequential Self-Compression (SSC)** in multi-agent hierarchies.
 
@@ -19,6 +20,7 @@ For full API reference, architecture details, examples, and integration guides,
 
 - [**Live Examples & Case Studies**](https://hakandamar.github.io/ct-toolkit/examples/): Real-world scenarios like Financial Auditor Integrity.
 - [**FastAPI Integration Test Project**](https://github.com/hakandamar/ct-toolkit-fastapi): Reference FastAPI app for validating CT Toolkit end-to-end across L1/L2/L3 guardrails and provenance logs with local model infrastructure.
+- [**Deep Agents Integration Test Project**](https://github.com/hakandamar/ct-toolkit-deep-agents): Reference Deep Agents app for validating CT Toolkit end-to-end with hierarchical agent workflows, L1/L2/L3 guardrails, and provenance logs.
 
 ---
 
@@ -74,16 +76,18 @@ ct-toolkit list-templates
 
 If you want a runnable application example instead of a CLI-only flow, see [**ct-toolkit-fastapi**](https://github.com/hakandamar/ct-toolkit-fastapi), a small FastAPI validation project that developers can use to test CT Toolkit locally with automated endpoints and pytest coverage.
 
+For Deep Agents workflows, see [**ct-toolkit-deep-agents**](https://github.com/hakandamar/ct-toolkit-deep-agents), a reference integration project for validating CT Toolkit in multi-agent orchestration scenarios.
+
 ---
 
 ## 🚦 Project Health & Status
 
-| Metric           | Status                                                  |
-| :--------------- | :------------------------------------------------------ |
-| **Tests**        | ✅ 330 passed, 0 failed (100% success rate, 93% coverage)                       |
+| Metric           | Status                                                                                                                                                                                                              |
+| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Tests**        | ✅ 397 passed, 3 skipped (100% success rate, 90% coverage)                                                                                                                                                           |
 | **Downloads**    | [![PyPI Downloads](https://static.pepy.tech/personalized-badge/ct-toolkit?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=MAGENTA&left_text=downloads)](https://pepy.tech/projects/ct-toolkit) |
-| **Last Phase**   | ✅ v0.3.20: Capability registry + role/environment policy metadata standardized across middleware  |
-| **Current Goal** | 🔶 Phase 7: Multi-Agent Synchronization (Integration)   |
+| **Last Phase**   | ✅ v0.3.22: CI/CD pipeline fix — Proper dependency installation via `uv sync --all-extras --dev` in GitHub Actions                                                                                                   |
+| **Current Goal** | 🔶 Phase 7: Multi-Agent Synchronization (Integration)                                                                                                                                                               |
 
 ### Framework & Model Support
 

ct_toolkit-0.3.22/ct_toolkit/core/__init__.py

@@ -0,0 +1,73 @@
+"""
+ct_toolkit.core
+===============
+Core components of the Computational Theseus Toolkit.
+
+This module provides:
+- ConstitutionalKernel: Ethical and behavioral core of the system
+- TheseusWrapper: LLM wrapper with constitutional guard
+- CompatibilityLayer: Template/kernel compatibility checking
+- ContextCompressionGuard: Context window protection
+- IntegrityMonitor: File integrity monitoring
+- Core exceptions
+"""
+
+from ct_toolkit.core.wrapper import TheseusWrapper, CTResponse, WrapperConfig
+from ct_toolkit.core.kernel import ConstitutionalKernel, KernelProfile, AxiomaticAnchor, PlasticCommitment
+from ct_toolkit.core.compatibility import CompatibilityLayer, CompatibilityLevel, CompatibilityResult
+from ct_toolkit.core.exceptions import (
+    CTToolkitError,
+    AxiomaticViolationError,
+    PlasticConflictError,
+    IncompatibleProfileError,
+)
+from ct_toolkit.core.compression_guard import ContextCompressionGuard
+from ct_toolkit.core.integrity import IntegrityMonitor
+from ct_toolkit.core.circuit_breaker import (
+    CircuitBreaker,
+    CircuitBreakerError,
+    CircuitBreakerStats,
+    CircuitBreakerRegistry,
+    CircuitState,
+)
+
+__all__ = [
+    # Wrapper
+    "TheseusWrapper",
+    "CTResponse",
+    "WrapperConfig",
+    # Kernel
+    "ConstitutionalKernel",
+    "KernelProfile",
+    "AxiomaticAnchor",
+    "PlasticCommitment",
+    # Compatibility
+    "CompatibilityLayer",
+    "CompatibilityLevel",
+    "CompatibilityResult",
+    # Compression
+    "ContextCompressionGuard",
+    # Integrity
+    "IntegrityMonitor",
+    # Circuit Breaker
+    "CircuitBreaker",
+    "CircuitBreakerError",
+    "CircuitBreakerStats",
+    "CircuitBreakerRegistry",
+    "CircuitState",
+    # Exceptions
+    "CTToolkitError",
+    "MissingClientError",
+    "KernelError",
+    "AxiomaticViolationError",
+    "PlasticConflictError",
+    "CompatibilityError",
+    "IncompatibleProfileError",
+    "DivergenceError",
+    "CriticalDivergenceError",
+    "CriticalSandboxDivergenceError",
+    "ProvenanceError",
+    "ChainIntegrityError",
+    "VaultError",
+    "ConfigurationTamperingError",
+]

ct_toolkit-0.3.22/ct_toolkit/core/async_wrapper.py

@@ -0,0 +1,226 @@
+"""
+ct_toolkit.core.async_wrapper
+==============================
+Async support for TheseusWrapper LLM calls.
+
+Provides:
+- AsyncTheseusWrapper: Async-compatible wrapper around TheseusWrapper
+- Async compatible circuit breaker integration
+
+Usage:
+    async with AsyncTheseusWrapper(client) as wrapper:
+        response = await wrapper.chat("Hello!")
+"""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Optional
+from pathlib import Path
+
+from ct_toolkit.core.wrapper import TheseusWrapper, CTResponse, WrapperConfig
+from ct_toolkit.core.circuit_breaker import CircuitBreaker, CircuitBreakerError, CircuitBreakerRegistry
+from ct_toolkit.utils.metrics import get_metrics_collector, MetricsCollector
+from ct_toolkit.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class AsyncTheseusWrapper:
+    """
+    Async-compatible TheseusWrapper.
+    
+    Provides async-compatible LLM calls with circuit breaker and metrics integration.
+    
+    Usage:
+        wrapper = AsyncTheseusWrapper(provider="openai")
+        response = await wrapper.chat("Hello!")
+        
+        # With circuit breaker
+        wrapper = AsyncTheseusWrapper(provider="openai", enable_circuit_breaker=True)
+    """
+    
+    def __init__(
+        self,
+        client: Any = None,
+        config: Optional[WrapperConfig] = None,
+        *,
+        provider: Optional[str] = None,
+        enable_circuit_breaker: bool = True,
+        circuit_breaker_threshold: int = 5,
+        circuit_breaker_recovery: float = 30.0,
+        metrics_enabled: bool = True,
+    ) -> None:
+        self._sync_wrapper = TheseusWrapper(
+            client=client,
+            config=config,
+            provider=provider,
+        )
+        self._metrics_enabled = metrics_enabled
+        self._metrics = get_metrics_collector() if metrics_enabled else None
+        
+        # Circuit breaker
+        self._circuit_breaker: Optional[CircuitBreaker] = None
+        if enable_circuit_breaker:
+            provider_name = self._sync_wrapper._provider or "unknown"
+            self._circuit_breaker = CircuitBreakerRegistry.global_instance().get_or_create(
+                name=f"llm-{provider_name}",
+                failure_threshold=circuit_breaker_threshold,
+                recovery_timeout=circuit_breaker_recovery,
+            )
+            logger.info(f"AsyncTheseusWrapper: Circuit breaker enabled for '{provider_name}'")
+    
+    @property
+    def sync_wrapper(self) -> TheseusWrapper:
+        """Get the underlying sync wrapper."""
+        return self._sync_wrapper
+    
+    async def chat(
+        self,
+        message: str,
+        *,
+        model: Optional[str] = None,
+        system: Optional[str] = None,
+        history: Optional[list[dict[str, str]]] = None,
+        **kwargs: Any,
+    ) -> CTResponse:
+        """
+        Send a message asynchronously and get response with identity protection.
+        
+        Uses run_in_executor to make sync LLM calls non-blocking.
+        """
+        if self._metrics:
+            self._metrics.increment("llm.requests.async.total", tags={
+                "provider": self._sync_wrapper._provider or "unknown",
+            })
+        
+        start_time = time.monotonic()
+        
+        try:
+            # Run sync wrapper in executor to not block event loop
+            loop = asyncio.get_event_loop()
+            response = await loop.run_in_executor(
+                None,
+                lambda: self._sync_wrapper.chat(
+                    message,
+                    model=model,
+                    system=system,
+                    history=history,
+                    **kwargs,
+                )
+            )
+            
+            # Record metrics
+            latency = time.monotonic() - start_time
+            if self._metrics:
+                self._metrics.record("llm.latency.async.seconds", latency, tags={
+                    "provider": self._sync_wrapper._provider or "unknown",
+                    "model": response.model,
+                })
+                self._metrics.increment("llm.requests.async.success", tags={
+                    "provider": self._sync_wrapper._provider or "unknown",
+                    "success": "true",
+                })
+            
+            return response
+            
+        except CircuitBreakerError as e:
+            # Circuit breaker is already tracking this
+            if self._metrics:
+                self._metrics.increment("llm.requests.async.circuit_breaker", tags={
+                    "provider": self._sync_wrapper._provider or "unknown",
+                    "state": e.state.value,
+                })
+            logger.warning(f"Circuit breaker open for LLM call: {e}")
+            raise
+        
+        except Exception as e:
+            # Record failure
+            latency = time.monotonic() - start_time
+            if self._metrics:
+                self._metrics.record("llm.latency.async.seconds", latency, tags={
+                    "provider": self._sync_wrapper._provider or "unknown",
+                })
+                self._metrics.increment("llm.requests.async.failure", tags={
+                    "provider": self._sync_wrapper._provider or "unknown",
+                    "success": "false",
+                    "error": type(e).__name__,
+                })
+            
+            # Record circuit breaker failure if applicable
+            if self._circuit_breaker:
+                try:
+                    self._circuit_breaker.record_failure()
+                except Exception:
+                    pass
+            
+            logger.error(f"Async LLM call failed: {type(e).__name__}: {e}")
+            raise
+    
+    async def health_check(self) -> dict[str, Any]:
+        """
+        Check health of the LLM connection.
+        
+        Returns status of circuit breaker and basic connectivity.
+        """
+        result: dict[str, Any] = {
+            "provider": self._sync_wrapper._provider or "unknown",
+            "status": "healthy",
+            "circuit_breaker": None,
+        }
+        
+        if self._circuit_breaker:
+            cb_state = self._circuit_breaker.state
+            cb_stats = self._circuit_breaker.get_stats().to_dict()
+            result["circuit_breaker"] = {
+                "state": cb_state.value,
+                "stats": cb_stats,
+                "time_until_recovery": self._circuit_breaker.time_until_recovery(),
+            }
+            if cb_state.value == "open":
+                result["status"] = "degraded"
+        
+        return result
+    
+    def get_metrics(self) -> Optional[dict[str, Any]]:
+        """Get current metrics."""
+        if not self._metrics:
+            return None
+        return self._metrics.get_all()
+    
+    def get_circuit_breaker_stats(self) -> Optional[dict[str, Any]]:
+        """Get circuit breaker statistics."""
+        if not self._circuit_breaker:
+            return None
+        return self._circuit_breaker.get_stats().to_dict()
+    
+    def reset_circuit_breaker(self) -> None:
+        """Manually reset the circuit breaker."""
+        if self._circuit_breaker:
+            self._circuit_breaker.reset()
+            logger.info("Circuit breaker manually reset")
+
+
+def create_async_wrapper(
+    provider: str = "openai",
+    model: Optional[str] = None,
+    enable_circuit_breaker: bool = True,
+    metrics_enabled: bool = True,
+) -> AsyncTheseusWrapper:
+    """
+    Factory function to create an AsyncTheseusWrapper.
+    
+    Args:
+        provider: LLM provider name.
+        model: Optional model override.
+        enable_circuit_breaker: Enable circuit breaker protection.
+        metrics_enabled: Enable metrics collection.
+    
+    Returns:
+        Configured AsyncTheseusWrapper instance.
+    """
+    return AsyncTheseusWrapper(
+        provider=provider,
+        enable_circuit_breaker=enable_circuit_breaker,
+        metrics_enabled=metrics_enabled,
+    )