ct-toolkit 0.3.6__tar.gz → 0.3.7__tar.gz

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.3.6
+Version: 0.3.7
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0
@@ -9,7 +9,7 @@ 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: litellm>=1.40.0
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pydantic>=2.5.0
@@ -20,6 +20,8 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: pyasn1>=0.6.3
 Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.29.0
 Provides-Extra: ollama
 Requires-Dist: ollama>=0.2.0; extra == "ollama"
 Provides-Extra: langchain
@@ -116,7 +118,7 @@ ct-toolkit list-templates
 
 | Metric           | Status                                                  |
 | :--------------- | :------------------------------------------------------ |
-| **Tests**        | ✅ 269/272 passing (92% coverage)                       |
+| **Tests**        | ✅ 281/292 passing (95% coverage)                       |
 | **Last Phase**   | ✅ Phase 6: Auditor Mode (Complete)                     |
 | **Current Goal** | 🔶 Phase 7: Multi-Agent Synchronization (Integration)   |
 

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/README.md

@@ -75,7 +75,7 @@ ct-toolkit list-templates
 
 | Metric           | Status                                                  |
 | :--------------- | :------------------------------------------------------ |
-| **Tests**        | ✅ 269/272 passing (92% coverage)                       |
+| **Tests**        | ✅ 281/292 passing (95% coverage)                       |
 | **Last Phase**   | ✅ Phase 6: Auditor Mode (Complete)                     |
 | **Current Goal** | 🔶 Phase 7: Multi-Agent Synchronization (Integration)   |
 

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit/__init__.py

@@ -23,7 +23,7 @@ from ct_toolkit.core.exceptions import (
     ChainIntegrityError,
 )
 
-__version__ = "0.3.6"
+__version__ = "0.3.7"
 
 __all__ = [
     "TheseusWrapper",

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit/cli.py

@@ -17,6 +17,7 @@ from rich.table import Table
 from ct_toolkit import TheseusWrapper, WrapperConfig, __version__
 from ct_toolkit.divergence.l3_icm import ICMRunner
 from ct_toolkit.core.kernel import ConstitutionalKernel
+from ct_toolkit.server import start_server
 
 app = typer.Typer(
     help="Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems.",
@@ -135,6 +136,37 @@ def audit(
     if not report.is_healthy:
         raise typer.Exit(code=1)
 
+@app.command()
+def serve(
+    host: str = typer.Option("127.0.0.1", "--host", help="Host to bind the server to."),
+    port: int = typer.Option(8001, "--port", help="Port to bind the server to."),
+    kernel: str = typer.Option("general", "--kernel", help="Name of the Constitutional Kernel to use."),
+    template: str = typer.Option("general", "--template", help="Name of the Identity Template to use."),
+    vault_path: str = typer.Option("./ct_provenance.db", "--vault", help="Path to the provenance log database."),
+    judge_provider: str = typer.Option("openai", "--judge-provider", help="LLM provider for the L2 judge."),
+    judge_model: Optional[str] = typer.Option(None, "--judge-model", help="Model ID for the L2 judge."),
+):
+    """Start the CT-Toolkit Guardrail Server for LiteLLM integration."""
+    console.print(f"Starting Guardrail Server...")
+    console.print(f"  - Kernel: [bold yellow]{kernel}[/bold yellow]")
+    console.print(f"  - Template: [bold green]{template}[/bold green]")
+    console.print(f"  - Bind: [bold cyan]{host}:{port}[/bold cyan]")
+    
+    try:
+        config = WrapperConfig(
+            kernel_name=kernel,
+            template=template,
+            vault_path=vault_path,
+            project_root=Path.cwd()
+        )
+        wrapper = TheseusWrapper(provider=judge_provider, config=config)
+        
+        # Start the uvicorn server
+        start_server(wrapper=wrapper, host=host, port=port)
+    except Exception as e:
+        console.print(f"[bold red]Failed to start server:[/bold red] {e}")
+        raise typer.Exit(code=1)
+
 @app.command()
 def list_kernels():
     """List available Constitutional Kernels."""

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit/core/wrapper.py

@@ -25,9 +25,7 @@ import os
 from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any, Iterator, Optional, Callable, Dict
-import any_llm
-from any_llm import AnyLLM
-import glob
+import litellm
 
 from ct_toolkit.core.kernel import ConstitutionalKernel
 from ct_toolkit.core.compatibility import CompatibilityLayer, CompatibilityResult
@@ -97,7 +95,7 @@ class TheseusWrapper:
     Identity-continuity proxy wrapping the LLM API client.
 
     Supported providers: openai (default), anthropic, ollama, google, etc.
-    (Any provider supported by any-llm-sdk)
+    (Any provider supported by LiteLLM)
 
     Usage:
         from ct_toolkit import TheseusWrapper
@@ -133,7 +131,7 @@ class TheseusWrapper:
                     Optional if 'provider' is specified.
             config:  Optional WrapperConfig instance.
             provider: Provider name (e.g. "openai", "anthropic", "ollama", "google", "cohere").
-                      If provided, 'any-llm' will be used to initialize the client internally.
+                      If provided, LiteLLM will be used to initialize the client internally.
             project_root: Path to the user's project root directory. Used to find a custom 'config/' folder.
                           Defaults to the current working directory.
         """
@@ -243,7 +241,7 @@ class TheseusWrapper:
             return client.lower()
 
         try:
-            # Check for any_llm wrapper
+            # Check for LiteLLM specific attributes if any
             if hasattr(client, "provider") and isinstance(client.provider, str):
                 return client.provider
 
@@ -501,7 +499,7 @@ class TheseusWrapper:
         model: str | None,
         **kwargs: Any,
     ) -> Any:
-        """Uses any_llm for unified provider calling."""
+        """Uses LiteLLM for unified provider calling."""
         # --- Passive Context Compression Detection ---
         if self._config.compression_passive_detection and self._shadow_history:
             # Simple heuristic: message count dropped significantly
@@ -514,8 +512,8 @@ class TheseusWrapper:
 
         # Update shadow history for next call
         self._shadow_history = list(messages)
-        # Convert messages to any_llm format if necessary
-        # any_llm.completion handles different formats internally
+        
+        # LiteLLM handles different message formats internally
         
         # Set default models per provider if not specified
         if not model:
@@ -524,32 +522,29 @@ class TheseusWrapper:
             elif self._provider == "ollama": model = "llama3"
             else: model = "gpt-4o-mini"
 
-        # any_llm expects "provider:model" format
+        # LiteLLM expects "provider/model" format for non-default providers
+        # Usually OpenAI models don't need a prefix.
         full_model = model
-        if ":" not in model:
-            full_model = f"{self._provider}:{model}"
-
-        # Prepare any_llm call
-        any_llm_kwargs = {
-            "model": full_model,
-            "messages": messages,
-            **kwargs
-        }
+        if ":" in model:
+             # If it has the legacy format "provider:model", convert it
+             full_model = model.replace(":", "/", 1)
+        elif self._provider not in ("openai", "unknown"):
+             full_model = f"{self._provider}/{model}"
 
         # Extract connection info from client if possible
         if hasattr(self._client, "base_url") and self._client.base_url:
-            any_llm_kwargs["api_base"] = str(self._client.base_url)
+            kwargs["api_base"] = str(self._client.base_url)
         if hasattr(self._client, "api_key") and self._client.api_key:
-            any_llm_kwargs["api_key"] = self._client.api_key
+            kwargs["api_key"] = self._client.api_key
 
         # Transfer common client configurations if available
-        if hasattr(self._client, "timeout") and "timeout" not in any_llm_kwargs:
-            any_llm_kwargs["timeout"] = self._client.timeout
+        if hasattr(self._client, "timeout") and "timeout" not in kwargs:
+            kwargs["timeout"] = self._client.timeout
 
         try:
-            return any_llm.completion(**any_llm_kwargs)
+            return litellm.completion(model=full_model, messages=messages, **kwargs)
         except Exception as e:
-            logger.error(f"any_llm call failed: {e}")
+            logger.error(f"litellm call failed: {e}")
             raise
 
     # ── Helper Methods ──────────────────────────────────────────────────────
@@ -603,25 +598,33 @@ class TheseusWrapper:
         return messages
 
     def _extract_content(self, raw: Any) -> str:
-        # Handle dict responses (e.g. from some mockers or raw APIs)
+        # Handle dict responses
         if isinstance(raw, dict):
             if "choices" in raw and isinstance(raw["choices"], list) and raw["choices"]:
-                # OpenAI dict format
                 return raw["choices"][0].get("message", {}).get("content", "") or ""
             if "message" in raw:
-                # Ollama dict format
+                # Ollama dictate format
                 return raw["message"].get("content", "") or ""
             return str(raw)
 
-        # OpenAI
-        if hasattr(raw, "choices"):
-            return raw.choices[0].message.content or ""
-        # Anthropic
-        if hasattr(raw, "content") and isinstance(raw.content, list):
-            return raw.content[0].text if raw.content else ""
-        # Ollama
-        if hasattr(raw, "message"):
-            return raw.message.content or ""
+        # LiteLLM ModelResponse (Standardized for all providers)
+        try:
+            if hasattr(raw, "choices") and raw.choices:
+                choice = raw.choices[0]
+                if hasattr(choice, "message") and choice.message:
+                    return choice.message.content or ""
+                # Some older/alternative formats
+                if hasattr(choice, "text"):
+                    return choice.text or ""
+        except Exception:
+            pass
+            
+        # Fallback raw extraction for edge cases
+        if hasattr(raw, "content") and isinstance(raw.content, list): # Anthropic style
+             return raw.content[0].text if raw.content else ""
+        if hasattr(raw, "message"): # Ollama generic style
+             return getattr(raw.message, "content", "") or ""
+             
         return str(raw)
 
     def _extract_model(self, raw: Any, fallback: str | None) -> str:

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit/divergence/l3_icm.py

@@ -19,7 +19,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 from typing import Any
 
-import any_llm
+import litellm
 
 from ct_toolkit.utils.logger import get_logger
 
@@ -290,11 +290,14 @@ class ICMRunner:
     def _call_model(self, prompt: str) -> str:
         system = self._kernel.get_system_prompt_injection()
 
+        # LiteLLM format
         full_model = self._model
-        if ":" not in self._model:
-            full_model = f"{self._provider}:{self._model}"
+        if ":" in self._model:
+            full_model = self._model.replace(":", "/", 1)
+        elif self._provider not in ("openai", "unknown"):
+            full_model = f"{self._provider}/{self._model}"
 
-        any_llm_kwargs = {
+        kwargs: dict[str, Any] = {
             "model": full_model,
             "messages": [
                 {"role": "system", "content": system},
@@ -306,13 +309,20 @@ class ICMRunner:
 
         # Extract connection info from client if possible
         if hasattr(self._client, "base_url") and self._client.base_url:
-            any_llm_kwargs["api_base"] = str(self._client.base_url)
+            kwargs["api_base"] = str(self._client.base_url)
         if hasattr(self._client, "api_key") and self._client.api_key:
-            any_llm_kwargs["api_key"] = self._client.api_key
+            kwargs["api_key"] = self._client.api_key
             
         try:
-            resp = any_llm.completion(**any_llm_kwargs)
-            # any_llm SDK standardizes responses but fallback handling preserves robustness
+            resp = litellm.completion(**kwargs)
+            
+            # Extract content from LiteLLM response
+            if hasattr(resp, "choices") and resp.choices:
+                choice = resp.choices[0]
+                if hasattr(choice, "message") and choice.message:
+                    return choice.message.content or ""
+            
+            # Fallback
             if isinstance(resp, dict):
                 if "choices" in resp and resp["choices"]:
                     return resp["choices"][0].get("message", {}).get("content", "")
@@ -320,16 +330,9 @@ class ICMRunner:
                     return resp["message"].get("content", "")
                 return str(resp)
 
-            if hasattr(resp, "choices"):
-                return resp.choices[0].message.content or ""
-            if hasattr(resp, "content") and isinstance(resp.content, list):
-                return resp.content[0].text if resp.content else ""
-            if hasattr(resp, "message"):
-                return resp.message.content or ""
-            
             return str(resp)
         except Exception as e:
-            logger.error(f"ICM probe any_llm call failed: {e}")
+            logger.error(f"ICM probe litellm call failed: {e}")
             raise
 
     # ── Probe Loading ──────────────────────────────────────────────────────────

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit/identity/embedding.py

@@ -9,9 +9,7 @@ Step 3 MVP implementation:
   - Each response embedding is calculated
   - Cosine distance = 1 - cosine_similarity → divergence score
 """
-from __future__ import annotations
-
-import json
+import litellm
 import hashlib
 from pathlib import Path
 from typing import Any
@@ -155,17 +153,21 @@ class IdentityEmbeddingLayer:
         """
         if self._embedding_client is not None:
             try:
-                # Robust attribute check for OpenAI-compatible clients
-                embeddings_api = getattr(self._embedding_client, "embeddings", None)
-                if embeddings_api:
-                    response = embeddings_api.create(
-                        input=[text],
-                        model=self._embedding_model
-                    )
-                    embedding = response.data[0].embedding
-                    return np.array(embedding, dtype=np.float32)
-                else:
-                    logger.debug("Embedding client does not support .embeddings API. Falling back.")
+                # Prepare arguments for litellm.embedding
+                kwargs: dict[str, Any] = {
+                    "model": self._embedding_model,
+                    "input": [text]
+                }
+                
+                # Transfer client configuration if available
+                if hasattr(self._embedding_client, "base_url") and self._embedding_client.base_url:
+                    kwargs["api_base"] = str(self._embedding_client.base_url)
+                if hasattr(self._embedding_client, "api_key") and self._embedding_client.api_key:
+                    kwargs["api_key"] = self._embedding_client.api_key
+                    
+                response = litellm.embedding(**kwargs)
+                embedding = response.data[0]["embedding"]
+                return np.array(embedding, dtype=np.float32)
             except Exception as e:
                 if self._strict_embedding:
                     raise RuntimeError(f"Embedding API failed: {e}") from e

ct_toolkit-0.3.7/ct_toolkit/middleware/litellm.py

@@ -0,0 +1,344 @@
+"""
+ct_toolkit.middleware.litellm
+------------------------------
+LiteLLM integration for identity-continuity guardrails.
+
+Provides ``TheseusLiteLLMCallback`` which hooks into LiteLLM's CustomLogger
+system to enforce Constitutional Kernel rules on every LLM call — regardless
+of which provider or model is being used underneath.
+
+This is the "Governance Proxy Middleware" pattern:
+  - Works with ANY provider LiteLLM supports (100+ models)
+  - No agent code changes required
+  - Pre-call: kernel validation → blocks axiomatic violations
+  - Post-call: divergence analysis + provenance logging
+
+Optional dependency — requires ``pip install 'ct-toolkit[litellm]'``.
+LiteLLM does NOT need to be installed for the rest of ct-toolkit to work.
+
+## SDK usage (direct litellm calls)::
+
+    import litellm
+    from ct_toolkit import TheseusWrapper, WrapperConfig
+    from ct_toolkit.middleware.litellm import TheseusLiteLLMCallback
+
+    wrapper = TheseusWrapper(provider="openai", kernel_name="defense")
+    handler = TheseusLiteLLMCallback(wrapper)
+
+    litellm.callbacks = [handler]
+
+    # All litellm.completion() calls are now identity-protected
+    response = litellm.completion(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "Hello!"}]
+    )
+
+## LiteLLM Proxy (proxy_config.yaml)::
+
+    model_list:
+      - model_name: gpt-4o-mini
+        litellm_params:
+          model: gpt-4o-mini
+
+    litellm_settings:
+      callbacks: ct_toolkit.middleware.litellm.proxy_handler_instance
+
+Compatible with litellm >= 1.40.0
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+from ct_toolkit.core.wrapper import TheseusWrapper, WrapperConfig
+from ct_toolkit.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+try:
+    from litellm.integrations.custom_logger import CustomLogger
+except ImportError as _exc:
+    raise ImportError(
+        "TheseusLiteLLMCallback requires litellm. "
+        "Install with: pip install 'litellm'"
+    ) from _exc
+
+
+class TheseusLiteLLMCallback(CustomLogger):
+    """
+    LiteLLM CustomLogger that enforces CT-Toolkit identity guardrails.
+
+    Hooks:
+      async_pre_call_hook      → Kernel validation (blocks axiomatic violations)
+      async_log_success_event  → Divergence engine + Provenance Log
+      async_log_failure_event  → Failure logging
+      log_success_event        → Sync fallback for non-async callers
+    """
+
+    def __init__(self, wrapper: TheseusWrapper) -> None:
+        super().__init__()
+        self.wrapper = wrapper
+        logger.info(
+            f"CT Toolkit | TheseusLiteLLMCallback initialized "
+            f"(kernel='{wrapper.kernel.name}', template='{wrapper._config.template}')"
+        )
+
+    # ── Pre-call: Axiomatic Kernel Validation ─────────────────────────────────
+
+    async def async_pre_call_hook(
+        self,
+        user_api_key_dict: Any,
+        cache: Any,
+        data: dict,
+        call_type: str,
+    ) -> Optional[str]:
+        """
+        Runs BEFORE the LLM API call.
+        Extracts user message and validates against Constitutional Kernel.
+
+        Returns:
+            None   → call proceeds normally
+            str    → LiteLLM returns this string as the response (call blocked)
+        """
+        messages = data.get("messages", [])
+        user_text = _extract_user_text(messages)
+
+        if not user_text:
+            return None
+
+        try:
+            self.wrapper.validate_user_rule(user_text)
+            return None  # All good, proceed
+        except Exception as e:
+            logger.warning(
+                f"CT Toolkit | LiteLLM pre-call kernel violation: {e} | "
+                f"model={data.get('model', 'unknown')}"
+            )
+            # Return blocked message — LiteLLM formats this into a proper response
+            return (
+                f"[CT Toolkit BLOCKED] This request violates an identity constraint "
+                f"and cannot be processed. Reason: {e}"
+            )
+
+    # ── Post-call: Divergence Analysis + Provenance ───────────────────────────
+
+    async def async_log_success_event(
+        self,
+        kwargs: dict,
+        response_obj: Any,
+        start_time: float,
+        end_time: float,
+    ) -> None:
+        """
+        Runs AFTER a successful LLM call.
+        Runs Divergence Engine and writes to Provenance Log.
+        """
+        try:
+            messages = kwargs.get("messages", [])
+            user_text = _extract_user_text(messages)
+            response_text = _extract_response_text(response_obj)
+            model = kwargs.get("model", "unknown")
+
+            if not response_text:
+                return
+
+            # Interaction count for Elasticity Scheduler
+            interaction_count = 0
+            if self.wrapper._config.log_requests:
+                interaction_count = self.wrapper._provenance_log.get_interaction_count(
+                    template=self.wrapper._config.template,
+                    kernel_name=self.wrapper.kernel.name,
+                    model=model,
+                )
+
+            # Run Divergence Engine (L1 → L2 → L3)
+            div_result = self.wrapper._run_divergence_engine(
+                message=user_text,
+                response=response_text,
+                interaction_count=interaction_count,
+            )
+
+            if getattr(div_result, 'cascade_blocked', False):
+                logger.warning(
+                    f"CT Toolkit | cascade_blocked=True via LiteLLM callback. "
+                    f"model={model} | score={div_result.l1_score:.4f} | "
+                    f"Consider halting downstream agent calls."
+                )
+
+            # Provenance Log
+            if self.wrapper._config.log_requests:
+                elapsed_ms = (end_time - start_time) * 1000 if isinstance(start_time, float) else 0.0
+                self.wrapper._provenance_log.record(
+                    request_text=user_text or "[LiteLLM Interaction]",
+                    response_text=response_text,
+                    divergence_score=div_result.l1_score,
+                    metadata={
+                        "middleware": "litellm",
+                        "provider": kwargs.get("custom_llm_provider", "unknown"),
+                        "model": model,
+                        "elapsed_ms": round(elapsed_ms, 2),
+                        "tier": div_result.tier.value,
+                        "cascade_blocked": getattr(div_result, 'cascade_blocked', False),
+                        "template": self.wrapper._config.template,
+                        "kernel": self.wrapper.kernel.name,
+                    },
+                )
+
+            logger.debug(
+                f"CT Toolkit | LiteLLM success | model={model} | "
+                f"divergence={div_result.l1_score:.4f} | tier={div_result.tier.value}"
+            )
+
+        except Exception as e:
+            # Never crash the caller — log and continue
+            logger.error(f"CT Toolkit | LiteLLM callback error (success event): {e}")
+
+    async def async_log_failure_event(
+        self,
+        kwargs: dict,
+        response_obj: Any,
+        start_time: float,
+        end_time: float,
+    ) -> None:
+        """Logs LLM failures to provenance for audit trail completeness."""
+        try:
+            model = kwargs.get("model", "unknown")
+            exception = kwargs.get("exception", "unknown error")
+            logger.warning(f"CT Toolkit | LiteLLM failure | model={model} | error={exception}")
+
+            if self.wrapper._config.log_requests:
+                messages = kwargs.get("messages", [])
+                self.wrapper._provenance_log.record(
+                    request_text=_extract_user_text(messages) or "[LiteLLM Failed Interaction]",
+                    response_text=f"[ERROR: {exception}]",
+                    divergence_score=None,
+                    metadata={
+                        "middleware": "litellm",
+                        "model": model,
+                        "status": "failed",
+                        "template": self.wrapper._config.template,
+                        "kernel": self.wrapper.kernel.name,
+                    },
+                )
+        except Exception as e:
+            logger.error(f"CT Toolkit | LiteLLM callback error (failure event): {e}")
+
+    # ── Sync fallback ─────────────────────────────────────────────────────────
+
+    def log_success_event(
+        self,
+        kwargs: dict,
+        response_obj: Any,
+        start_time: float,
+        end_time: float,
+    ) -> None:
+        """Sync fallback — runs divergence + provenance for non-async callers."""
+        try:
+            messages = kwargs.get("messages", [])
+            user_text = _extract_user_text(messages)
+            response_text = _extract_response_text(response_obj)
+            model = kwargs.get("model", "unknown")
+
+            if not response_text:
+                return
+
+            div_result = self.wrapper._run_divergence_engine(
+                message=user_text,
+                response=response_text,
+            )
+
+            if self.wrapper._config.log_requests:
+                self.wrapper._provenance_log.record(
+                    request_text=user_text or "[LiteLLM Interaction]",
+                    response_text=response_text,
+                    divergence_score=div_result.l1_score,
+                    metadata={
+                        "middleware": "litellm",
+                        "model": model,
+                        "tier": div_result.tier.value,
+                        "template": self.wrapper._config.template,
+                        "kernel": self.wrapper.kernel.name,
+                    },
+                )
+        except Exception as e:
+            logger.error(f"CT Toolkit | LiteLLM callback error (sync success): {e}")
+
+
+# ── Proxy Mode: singleton instance for proxy_config.yaml ─────────────────────
+
+def create_proxy_handler(
+    kernel_name: str = "default",
+    template: str = "general",
+    vault_path: str = "./ct_provenance.db",
+    enterprise_mode: bool = False,
+) -> TheseusLiteLLMCallback:
+    """
+    Factory for LiteLLM Proxy mode.
+
+    Usage in proxy_config.yaml::
+
+        litellm_settings:
+          callbacks: ct_toolkit.middleware.litellm.proxy_handler_instance
+
+    Or with custom config::
+
+        # custom_callbacks.py
+        from ct_toolkit.middleware.litellm import create_proxy_handler
+        proxy_handler_instance = create_proxy_handler(kernel_name="defense", template="defense")
+    """
+    wrapper = TheseusWrapper(
+        provider="openai",  # Proxy doesn't need a specific provider
+        config=WrapperConfig(
+            kernel_name=kernel_name,
+            template=template,
+            vault_path=vault_path,
+            enterprise_mode=enterprise_mode,
+        ),
+    )
+    return TheseusLiteLLMCallback(wrapper)
+
+
+# Default proxy singleton — works out-of-the-box for proxy_config.yaml
+proxy_handler_instance = create_proxy_handler()
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _extract_user_text(messages: list[dict]) -> str:
+    """Extract non-system message content from LiteLLM messages list."""
+    parts = []
+    for msg in messages:
+        if isinstance(msg, dict) and msg.get("role") != "system":
+            content = msg.get("content", "")
+            if isinstance(content, str):
+                parts.append(content)
+            elif isinstance(content, list):
+                # Handle multimodal content blocks
+                for block in content:
+                    if isinstance(block, dict) and block.get("type") == "text":
+                        parts.append(block.get("text", ""))
+    return " ".join(parts)
+
+
+def _extract_response_text(response_obj: Any) -> str:
+    """Extract text content from LiteLLM ModelResponse."""
+    if response_obj is None:
+        return ""
+    try:
+        # Standard LiteLLM ModelResponse
+        if hasattr(response_obj, "choices"):
+            if not response_obj.choices:
+                return ""  # Empty choices list
+            choice = response_obj.choices[0]
+            if hasattr(choice, "message") and choice.message:
+                return choice.message.content or ""
+            if hasattr(choice, "text"):
+                return choice.text or ""
+        # Dict format
+        if isinstance(response_obj, dict):
+            choices = response_obj.get("choices", [])
+            if choices:
+                return choices[0].get("message", {}).get("content", "")
+    except Exception:
+        pass
+    return str(response_obj)

ct_toolkit-0.3.7/ct_toolkit/server.py

@@ -0,0 +1,174 @@
+"""
+ct_toolkit.server
+-----------------
+FastAPI server for LiteLLM Generic Guardrail API.
+Exposes /guardrail/check to LiteLLM for pre-call and post-call validation.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+from fastapi import FastAPI, Body, HTTPException
+from pydantic import BaseModel, Field
+import uvicorn
+
+from ct_toolkit.core.wrapper import TheseusWrapper
+from ct_toolkit.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+# This will be injected by the CLI when starting the server
+_wrapper_instance: Optional[TheseusWrapper] = None
+
+app = FastAPI(
+    title="CT-Toolkit Guardrail Server",
+    description="Identity Continuity Guardrails for Agentic Systems via LiteLLM Generic Guardrail API.",
+    version="1.0.0"
+)
+
+class GuardrailRequest(BaseModel):
+    """LiteLLM Generic Guardrail API Request Schema."""
+    texts: Optional[List[str]] = Field(None, description="Extracted text from the request.")
+    input_type: str = Field(..., description="Phase of the call: 'request' or 'response'.")
+    structured_messages: Optional[List[Dict[str, Any]]] = Field(None, description="Full messages in OpenAI format.")
+    images: Optional[List[str]] = None
+    tools: Optional[List[Any]] = None
+    tool_calls: Optional[List[Any]] = None
+    request_data: Optional[Dict[str, Any]] = None
+    litellm_call_id: Optional[str] = None
+    litellm_trace_id: Optional[str] = None
+
+class GuardrailResponse(BaseModel):
+    """LiteLLM Generic Guardrail API Response Schema."""
+    action: str = Field(..., description="'BLOCKED' | 'NONE' | 'GUARDRAIL_INTERVENED'")
+    blocked_reason: Optional[str] = Field(None, description="Reason for denial (required if BLOCKED).")
+    texts: Optional[List[str]] = Field(None, description="Optional array of modified text strings.")
+
+@app.post("/guardrail/check", response_model=GuardrailResponse)
+async def check_guardrail(request: GuardrailRequest):
+    """
+    Main endpoint for LiteLLM Generic Guardrail API.
+    """
+    global _wrapper_instance
+    if not _wrapper_instance:
+        raise HTTPException(status_code=500, detail="Server not initialized with a Constitutional Kernel.")
+
+    logger.info(f"Received {request.input_type} check (call_id={request.litellm_call_id})")
+
+    try:
+        if request.input_type == "request":
+            return await _handle_pre_call(request)
+        elif request.input_type == "response":
+            return await _handle_post_call(request)
+        else:
+            logger.warning(f"Unknown input_type: {request.input_type}")
+            return GuardrailResponse(action="NONE")
+    except Exception as e:
+        logger.error(f"Error during guardrail check: {e}")
+        # Default to NONE to avoid breaking production flows on server error
+        return GuardrailResponse(action="NONE")
+
+async def _handle_pre_call(request: GuardrailRequest) -> GuardrailResponse:
+    """Validate user message against Constitutional Kernel before LLM call."""
+    user_text = ""
+    if request.texts is not None:
+        user_text = " ".join(request.texts)
+    elif request.structured_messages is not None:
+        user_text = _extract_user_text(request.structured_messages)
+
+    if user_text:
+        try:
+            _wrapper_instance.validate_user_rule(user_text)
+            return GuardrailResponse(action="NONE")
+        except Exception as e:
+            logger.warning(f"Pre-call kernel violation: {e}")
+            return GuardrailResponse(
+                action="BLOCKED",
+                blocked_reason=f"Identity constraint violation: {e}"
+            )
+    return GuardrailResponse(action="NONE")
+
+async def _handle_post_call(request: GuardrailRequest) -> GuardrailResponse:
+    """Analyze LLM response for divergence after call."""
+    user_text = ""
+    if request.structured_messages is not None:
+        user_text = _extract_user_text(request.structured_messages)
+
+    response_text = ""
+    if request.texts is not None:
+        response_text = " ".join(request.texts)
+    
+    if not response_text:
+        return GuardrailResponse(action="NONE")
+
+    model = "unknown"
+    if request.request_data:
+        # LiteLLM might not send the model directly here, but we can try to extract from metadata
+        pass
+
+    interaction_count = 0
+    if _wrapper_instance._config.log_requests:
+        interaction_count = _wrapper_instance._provenance_log.get_interaction_count(
+            template=_wrapper_instance._config.template,
+            kernel_name=_wrapper_instance.kernel.name,
+            model=model,
+        )
+
+    # Run Divergence Engine
+    div_result = _wrapper_instance._run_divergence_engine(
+        message=user_text,
+        response=response_text,
+        interaction_count=interaction_count,
+    )
+
+    # Record to Provenance Log
+    if _wrapper_instance._config.log_requests:
+        _wrapper_instance._provenance_log.record(
+            request_text=user_text or "[Generic Guardrail Interaction]",
+            response_text=response_text,
+            divergence_score=div_result.l1_score,
+            metadata={
+                "middleware": "generic_guardrail_api",
+                "model": model,
+                "tier": div_result.tier.value,
+                "template": _wrapper_instance._config.template,
+                "kernel": _wrapper_instance.kernel.name,
+                "litellm_call_id": request.litellm_call_id,
+            },
+        )
+
+    # Handle cascade_blocked
+    if getattr(div_result, 'cascade_blocked', False):
+         return GuardrailResponse(
+            action="BLOCKED",
+            blocked_reason=f"Identity drift detected (score={div_result.l1_score:.4f})"
+        )
+
+    return GuardrailResponse(action="NONE")
+
+def _extract_user_text(messages: List[Dict[str, Any]]) -> str:
+    """Extract non-system message content from messages list."""
+    parts = []
+    for msg in messages:
+        if msg.get("role") != "system":
+            content = msg.get("content", "")
+            if isinstance(content, str):
+                parts.append(content)
+    return " ".join(parts)
+
+def _extract_response_text(response_obj: Any) -> str:
+    """Extract text content from LiteLLM response object."""
+    try:
+        if isinstance(response_obj, dict):
+            choices = response_obj.get("choices", [])
+            if choices:
+                return choices[0].get("message", {}).get("content", "")
+    except Exception:
+        pass
+    return ""
+
+def start_server(wrapper: TheseusWrapper, host: str, port: int):
+    """Inject wrapper and start uvicorn server."""
+    global _wrapper_instance
+    _wrapper_instance = wrapper
+    logger.info(f"Starting Guardrail Server on {host}:{port}")
+    uvicorn.run(app, host=host, port=port)

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ct-toolkit
-Version: 0.3.6
+Version: 0.3.7
 Summary: Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems
 Author: Hakan Damar
 License: Apache-2.0
@@ -9,7 +9,7 @@ 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: litellm>=1.40.0
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: pydantic>=2.5.0
@@ -20,6 +20,8 @@ Requires-Dist: rich>=13.0.0
 Requires-Dist: jinja2>=3.1.0
 Requires-Dist: pyasn1>=0.6.3
 Requires-Dist: typer[all]>=0.12.0
+Requires-Dist: fastapi>=0.110.0
+Requires-Dist: uvicorn>=0.29.0
 Provides-Extra: ollama
 Requires-Dist: ollama>=0.2.0; extra == "ollama"
 Provides-Extra: langchain
@@ -116,7 +118,7 @@ ct-toolkit list-templates
 
 | Metric           | Status                                                  |
 | :--------------- | :------------------------------------------------------ |
-| **Tests**        | ✅ 269/272 passing (92% coverage)                       |
+| **Tests**        | ✅ 281/292 passing (95% coverage)                       |
 | **Last Phase**   | ✅ Phase 6: Auditor Mode (Complete)                     |
 | **Current Goal** | 🔶 Phase 7: Multi-Agent Synchronization (Integration)   |
 

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 ct_toolkit/__init__.py
 ct_toolkit/__main__.py
 ct_toolkit/cli.py
+ct_toolkit/server.py
 ct_toolkit.egg-info/PKG-INFO
 ct_toolkit.egg-info/SOURCES.txt
 ct_toolkit.egg-info/dependency_links.txt
@@ -42,6 +43,7 @@ ct_toolkit/middleware/autogen.py
 ct_toolkit/middleware/crewai.py
 ct_toolkit/middleware/deepagents.py
 ct_toolkit/middleware/langchain.py
+ct_toolkit/middleware/litellm.py
 ct_toolkit/provenance/__init__.py
 ct_toolkit/provenance/log.py
 ct_toolkit/provenance/vault/__init__.py

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/ct_toolkit.egg-info/requires.txt

@@ -1,5 +1,5 @@
 instructor>=1.3.0
-any-llm-sdk[all]>=1.0.0
+litellm>=1.40.0
 numpy>=1.26.0
 pyyaml>=6.0
 pydantic>=2.5.0
@@ -10,6 +10,8 @@ rich>=13.0.0
 jinja2>=3.1.0
 pyasn1>=0.6.3
 typer[all]>=0.12.0
+fastapi>=0.110.0
+uvicorn>=0.29.0
 
 [autogen]
 pyautogen>=0.4.0

{ct_toolkit-0.3.6 → ct_toolkit-0.3.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ct-toolkit"
-version = "0.3.6"
+version = "0.3.7"
 description = "Computational Theseus Toolkit — Identity Continuity Guardrails for Agentic Systems"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -14,7 +14,7 @@ keywords = ["llm", "ai-safety", "identity-continuity", "guardrails", "alignment"
 
 dependencies = [
     "instructor>=1.3.0",
-    "any-llm-sdk[all]>=1.0.0",
+    "litellm>=1.40.0",
     "numpy>=1.26.0",
     "pyyaml>=6.0",
     "pydantic>=2.5.0",
@@ -25,6 +25,8 @@ dependencies = [
     "jinja2>=3.1.0",
     "pyasn1>=0.6.3",
     "typer[all]>=0.12.0",
+    "fastapi>=0.110.0",
+    "uvicorn>=0.29.0",
 ]
 
 [project.optional-dependencies]