epi-recorder 2.2.0__py3-none-any.whl → 2.3.0__py3-none-any.whl

epi_core/schemas.py

@@ -18,7 +18,7 @@ class ManifestModel(BaseModel):
     """
     
     spec_version: str = Field(
-        default="2.2.0",
+        default="2.3.0",
         description="EPI specification version"
     )
     
@@ -148,5 +148,5 @@ class StepModel(BaseModel):
     )
 
 
-
+
  

epi_recorder/__init__.py

@@ -4,7 +4,7 @@ EPI Recorder - Runtime interception and workflow capture.
 Python API for recording AI workflows with cryptographic verification.
 """
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 # Export Python API
 from epi_recorder.api import (
@@ -13,13 +13,21 @@ from epi_recorder.api import (
     get_current_session
 )
 
+# Export wrapper clients (new in v2.3.0)
+from epi_recorder.wrappers import (
+    wrap_openai,
+    TracedOpenAI,
+)
+
 __all__ = [
     "EpiRecorderSession",
     "record",
     "get_current_session",
+    "wrap_openai",
+    "TracedOpenAI",
     "__version__"
 ]
 
 
-
+
  

epi_recorder/api.py

@@ -54,6 +54,8 @@ class EpiRecorderSession:
         metrics: Optional[Dict[str, Union[float, str]]] = None,
         approved_by: Optional[str] = None,
         metadata_tags: Optional[List[str]] = None,  # Renamed to avoid conflict with tags parameter
+        # Legacy mode (deprecated)
+        legacy_patching: bool = False,
     ):
         """
         Initialize EPI recording session.
@@ -70,6 +72,7 @@ class EpiRecorderSession:
             metrics: Key-value metrics for this workflow (accuracy, latency, etc.)
             approved_by: Person or entity who approved this workflow execution
             metadata_tags: Tags for categorizing this workflow (renamed from tags to avoid conflict)
+            legacy_patching: Enable deprecated monkey patching mode (default: False)
         """
         self.output_path = Path(output_path)
         self.workflow_name = workflow_name or "untitled"
@@ -85,6 +88,9 @@ class EpiRecorderSession:
         self.approved_by = approved_by
         self.metadata_tags = metadata_tags
         
+        # Legacy mode flag (deprecated)
+        self.legacy_patching = legacy_patching
+        
         # Runtime state
         self.temp_dir: Optional[Path] = None
         self.recording_context: Optional[RecordingContext] = None
@@ -117,9 +123,17 @@ class EpiRecorderSession:
         set_recording_context(self.recording_context)
         _thread_local.active_session = self
         
-        # Patch LLM libraries and HTTP
-        from epi_recorder.patcher import patch_all
-        patch_all()
+        # Only patch LLM libraries if legacy mode is enabled (deprecated)
+        if self.legacy_patching:
+            import warnings
+            warnings.warn(
+                "legacy_patching is deprecated and will be removed in v3.0.0. "
+                "Use epi.log_llm_call() or wrapper clients (wrap_openai) instead.",
+                DeprecationWarning,
+                stacklevel=2
+            )
+            from epi_recorder.patcher import patch_all
+            patch_all()
         
         # Log session start
         self.log_step("session.start", {
@@ -250,6 +264,172 @@ class EpiRecorderSession:
             **response_payload
         })
     
+    def log_llm_call(
+        self, 
+        response: Any, 
+        messages: Optional[List[Dict[str, str]]] = None,
+        provider: str = "auto"
+    ) -> None:
+        """
+        Log a complete LLM call (request + response) from any provider.
+        
+        Auto-detects OpenAI, Anthropic, and Gemini response objects.
+        This is the RECOMMENDED way to log LLM calls without monkey patching.
+        
+        Args:
+            response: The LLM response object (OpenAI, Anthropic, Gemini, etc.)
+            messages: Optional original messages (for request logging)
+            provider: Provider name ("auto" to detect, or "openai", "anthropic", etc.)
+            
+        Example:
+            with record("my_agent.epi") as epi:
+                response = client.chat.completions.create(
+                    model="gpt-4",
+                    messages=[{"role": "user", "content": "Hello"}]
+                )
+                epi.log_llm_call(response, messages=[{"role": "user", "content": "Hello"}])
+        """
+        if not self._entered:
+            raise RuntimeError("Cannot log LLM call outside of context manager")
+        
+        # Auto-detect provider and extract data
+        model = "unknown"
+        content = ""
+        usage = None
+        choices = []
+        
+        # Try OpenAI format
+        if hasattr(response, "choices") and hasattr(response, "model"):
+            provider = "openai" if provider == "auto" else provider
+            model = getattr(response, "model", "unknown")
+            
+            for choice in response.choices:
+                msg = choice.message
+                choices.append({
+                    "message": {
+                        "role": getattr(msg, "role", "assistant"),
+                        "content": getattr(msg, "content", ""),
+                    },
+                    "finish_reason": getattr(choice, "finish_reason", None),
+                })
+                if not content:
+                    content = getattr(msg, "content", "")
+            
+            if hasattr(response, "usage") and response.usage:
+                usage = {
+                    "prompt_tokens": getattr(response.usage, "prompt_tokens", 0),
+                    "completion_tokens": getattr(response.usage, "completion_tokens", 0),
+                    "total_tokens": getattr(response.usage, "total_tokens", 0),
+                }
+        
+        # Try Anthropic format
+        elif hasattr(response, "content") and hasattr(response, "model"):
+            provider = "anthropic" if provider == "auto" else provider
+            model = getattr(response, "model", "unknown")
+            
+            # Anthropic returns content as a list of content blocks
+            content_blocks = getattr(response, "content", [])
+            if content_blocks and hasattr(content_blocks[0], "text"):
+                content = content_blocks[0].text
+            choices = [{"message": {"role": "assistant", "content": content}}]
+            
+            if hasattr(response, "usage"):
+                usage = {
+                    "input_tokens": getattr(response.usage, "input_tokens", 0),
+                    "output_tokens": getattr(response.usage, "output_tokens", 0),
+                }
+        
+        # Try Gemini format
+        elif hasattr(response, "text") and hasattr(response, "candidates"):
+            provider = "gemini" if provider == "auto" else provider
+            model = "gemini"
+            content = getattr(response, "text", "")
+            choices = [{"message": {"role": "assistant", "content": content}}]
+        
+        # Fallback: try to extract as dict or string
+        else:
+            provider = provider if provider != "auto" else "unknown"
+            if isinstance(response, dict):
+                content = str(response.get("content", response))
+            else:
+                content = str(response)
+            choices = [{"message": {"role": "assistant", "content": content}}]
+        
+        # Log request if messages provided
+        if messages:
+            self.log_step("llm.request", {
+                "provider": provider,
+                "model": model,
+                "messages": messages,
+                "timestamp": datetime.utcnow().isoformat(),
+            })
+        
+        # Log response
+        response_data = {
+            "provider": provider,
+            "model": model,
+            "choices": choices,
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+        if usage:
+            response_data["usage"] = usage
+        
+        self.log_step("llm.response", response_data)
+    
+    def log_chat(
+        self,
+        model: str,
+        messages: List[Dict[str, str]],
+        response_content: str,
+        provider: str = "custom",
+        usage: Optional[Dict[str, int]] = None,
+        **metadata
+    ) -> None:
+        """
+        Simplified logging for chat completions.
+        
+        Use this when you have the raw data instead of response objects.
+        
+        Args:
+            model: Model name (e.g., "gpt-4", "claude-3")
+            messages: The messages sent to the model
+            response_content: The assistant's response text
+            provider: Provider name (default: "custom")
+            usage: Optional token usage dict
+            **metadata: Additional metadata to include
+            
+        Example:
+            epi.log_chat(
+                model="gpt-4",
+                messages=[{"role": "user", "content": "Hello"}],
+                response_content="Hi there!",
+                tokens=150
+            )
+        """
+        if not self._entered:
+            raise RuntimeError("Cannot log chat outside of context manager")
+        
+        # Log request
+        self.log_step("llm.request", {
+            "provider": provider,
+            "model": model,
+            "messages": messages,
+            "timestamp": datetime.utcnow().isoformat(),
+            **metadata
+        })
+        
+        # Log response
+        response_data = {
+            "provider": provider,
+            "model": model,
+            "choices": [{"message": {"role": "assistant", "content": response_content}}],
+            "timestamp": datetime.utcnow().isoformat(),
+        }
+        if usage:
+            response_data["usage"] = usage
+        
+        self.log_step("llm.response", response_data)
+    
     def log_artifact(
         self,
         file_path: Path,
@@ -615,5 +795,5 @@ def get_current_session() -> Optional[EpiRecorderSession]:
     return getattr(_thread_local, 'active_session', None)
 
 
-
+
  

epi_recorder/patcher.py

@@ -47,6 +47,9 @@ class RecordingContext:
         
         # Keep JSONL path for backwards compatibility
         self.steps_file = self.output_dir / "steps.jsonl"
+        
+        # Create empty steps.jsonl file immediately (for tests and early access)
+        self.steps_file.touch(exist_ok=True)
     
     def add_step(self, kind: str, content: Dict[str, Any]) -> None:
         """
@@ -171,8 +174,9 @@ def _patch_openai_v1() -> bool:
         from openai import OpenAI
         from openai.resources.chat import completions
         
-        # Store original method
+        # Store original method for unpatching
         original_create = completions.Completions.create
+        _original_methods["openai.chat.completions.create"] = original_create
         
         @wraps(original_create)
         def wrapped_create(self, *args, **kwargs):
@@ -550,17 +554,53 @@ def patch_all() -> Dict[str, bool]:
     return results
 
 
+# Store original methods for unpatching
+_original_methods: Dict[str, Any] = {}
+
+
 def unpatch_all() -> None:
     """
     Unpatch all providers (restore original methods).
     
-    Note: This is a placeholder for future implementation.
-    Full unpatching requires storing original methods.
+    Restores any methods that were patched by patch_all(), patch_openai(),
+    patch_gemini(), or patch_requests().
     """
-    # For MVP, we don't implement unpatching
-    # In production, store original methods and restore them
-    pass
+    global _original_methods
+    
+    # Restore OpenAI v1+ if patched
+    if "openai.chat.completions.create" in _original_methods:
+        try:
+            from openai.resources.chat import completions
+            completions.Completions.create = _original_methods["openai.chat.completions.create"]
+        except ImportError:
+            pass
+    
+    # Restore OpenAI legacy if patched
+    if "openai.ChatCompletion.create" in _original_methods:
+        try:
+            import openai
+            openai.ChatCompletion.create = _original_methods["openai.ChatCompletion.create"]
+        except (ImportError, AttributeError):
+            pass
+    
+    # Restore Gemini if patched
+    if "gemini.generate_content" in _original_methods:
+        try:
+            import google.generativeai as genai
+            genai.GenerativeModel.generate_content = _original_methods["gemini.generate_content"]
+        except ImportError:
+            pass
+    
+    # Restore requests if patched
+    if "requests.Session.request" in _original_methods:
+        try:
+            import requests
+            requests.Session.request = _original_methods["requests.Session.request"]
+        except ImportError:
+            pass
+    
+    # Clear stored originals
+    _original_methods.clear()
 
 
-
  

epi_recorder/wrappers/__init__.py

@@ -0,0 +1,16 @@
+"""
+EPI Wrapper Clients - Proxy wrappers for LLM clients.
+
+Provides transparent tracing without monkey patching.
+"""
+
+from epi_recorder.wrappers.openai import wrap_openai, TracedOpenAI, TracedCompletions, TracedChat
+from epi_recorder.wrappers.base import TracedClientBase
+
+__all__ = [
+    "wrap_openai",
+    "TracedOpenAI",
+    "TracedCompletions",
+    "TracedChat",
+    "TracedClientBase",
+]

epi_recorder/wrappers/base.py

@@ -0,0 +1,79 @@
+"""
+Base classes for EPI traced clients.
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+from datetime import datetime
+
+
+class TracedClientBase(ABC):
+    """
+    Base class for traced LLM client wrappers.
+    
+    Provides common functionality for logging LLM calls
+    to the active EPI recording session.
+    """
+    
+    def __init__(self, client: Any):
+        """
+        Initialize traced client wrapper.
+        
+        Args:
+            client: The original LLM client to wrap
+        """
+        self._client = client
+    
+    def _get_session(self):
+        """Get the current active EPI recording session."""
+        from epi_recorder.api import get_current_session
+        return get_current_session()
+    
+    def _log_request(self, provider: str, model: str, messages: list, **kwargs) -> None:
+        """Log an LLM request to the active session."""
+        session = self._get_session()
+        if session:
+            session.log_step("llm.request", {
+                "provider": provider,
+                "model": model,
+                "messages": messages,
+                "timestamp": datetime.utcnow().isoformat(),
+                **kwargs
+            })
+    
+    def _log_response(
+        self, 
+        provider: str, 
+        model: str, 
+        content: str,
+        usage: Optional[dict] = None,
+        latency_seconds: Optional[float] = None,
+        **kwargs
+    ) -> None:
+        """Log an LLM response to the active session."""
+        session = self._get_session()
+        if session:
+            response_data = {
+                "provider": provider,
+                "model": model,
+                "choices": [{"message": {"role": "assistant", "content": content}}],
+                "timestamp": datetime.utcnow().isoformat(),
+            }
+            if usage:
+                response_data["usage"] = usage
+            if latency_seconds is not None:
+                response_data["latency_seconds"] = round(latency_seconds, 3)
+            response_data.update(kwargs)
+            session.log_step("llm.response", response_data)
+    
+    def _log_error(self, provider: str, error: Exception, **kwargs) -> None:
+        """Log an LLM error to the active session."""
+        session = self._get_session()
+        if session:
+            session.log_step("llm.error", {
+                "provider": provider,
+                "error": str(error),
+                "error_type": type(error).__name__,
+                "timestamp": datetime.utcnow().isoformat(),
+                **kwargs
+            })

epi_recorder/wrappers/openai.py

@@ -0,0 +1,178 @@
+"""
+OpenAI wrapper for EPI tracing.
+
+Provides a proxy wrapper that automatically logs all LLM calls
+without monkey patching.
+"""
+
+import time
+from typing import Any, Optional
+from datetime import datetime
+
+from epi_recorder.wrappers.base import TracedClientBase
+
+
+class TracedCompletions:
+    """Proxy wrapper for openai.chat.completions."""
+    
+    def __init__(self, completions: Any, provider: str = "openai"):
+        self._completions = completions
+        self._provider = provider
+    
+    def _get_session(self):
+        """Get the current active EPI recording session."""
+        from epi_recorder.api import get_current_session
+        return get_current_session()
+    
+    def create(self, *args, **kwargs) -> Any:
+        """
+        Create a chat completion with automatic EPI tracing.
+        
+        All arguments are passed through to the underlying client.
+        """
+        session = self._get_session()
+        
+        # Extract request info
+        model = kwargs.get("model", "unknown")
+        messages = kwargs.get("messages", [])
+        
+        # Log request if session is active
+        if session:
+            session.log_step("llm.request", {
+                "provider": self._provider,
+                "model": model,
+                "messages": messages,
+                "timestamp": datetime.utcnow().isoformat(),
+            })
+        
+        # Call original method
+        start_time = time.time()
+        try:
+            response = self._completions.create(*args, **kwargs)
+            latency = time.time() - start_time
+            
+            # Log response if session is active
+            if session:
+                # Extract response content
+                choices = []
+                for choice in response.choices:
+                    msg = choice.message
+                    choices.append({
+                        "message": {
+                            "role": getattr(msg, "role", "assistant"),
+                            "content": getattr(msg, "content", ""),
+                        },
+                        "finish_reason": getattr(choice, "finish_reason", None),
+                    })
+                
+                # Extract usage
+                usage = None
+                if hasattr(response, "usage") and response.usage:
+                    usage = {
+                        "prompt_tokens": getattr(response.usage, "prompt_tokens", 0),
+                        "completion_tokens": getattr(response.usage, "completion_tokens", 0),
+                        "total_tokens": getattr(response.usage, "total_tokens", 0),
+                    }
+                
+                session.log_step("llm.response", {
+                    "provider": self._provider,
+                    "model": model,
+                    "choices": choices,
+                    "usage": usage,
+                    "latency_seconds": round(latency, 3),
+                    "timestamp": datetime.utcnow().isoformat(),
+                })
+            
+            return response
+            
+        except Exception as e:
+            latency = time.time() - start_time
+            
+            # Log error if session is active
+            if session:
+                session.log_step("llm.error", {
+                    "provider": self._provider,
+                    "model": model,
+                    "error": str(e),
+                    "error_type": type(e).__name__,
+                    "latency_seconds": round(latency, 3),
+                    "timestamp": datetime.utcnow().isoformat(),
+                })
+            
+            raise
+
+
+class TracedChat:
+    """Proxy wrapper for openai.chat."""
+    
+    def __init__(self, chat: Any, provider: str = "openai"):
+        self._chat = chat
+        self._provider = provider
+        self.completions = TracedCompletions(chat.completions, provider)
+
+
+class TracedOpenAI(TracedClientBase):
+    """
+    Traced OpenAI client wrapper.
+    
+    Wraps an OpenAI client and automatically logs all LLM calls
+    to the active EPI recording session.
+    
+    Usage:
+        from openai import OpenAI
+        from epi_recorder.wrappers import wrap_openai
+        
+        client = wrap_openai(OpenAI())
+        
+        with record("my_agent.epi"):
+            response = client.chat.completions.create(
+                model="gpt-4",
+                messages=[{"role": "user", "content": "Hello"}]
+            )
+    """
+    
+    def __init__(self, client: Any, provider: str = "openai"):
+        """
+        Initialize traced OpenAI client.
+        
+        Args:
+            client: OpenAI client instance
+            provider: Provider name for logging (default: "openai")
+        """
+        super().__init__(client)
+        self._provider = provider
+        self.chat = TracedChat(client.chat, provider)
+    
+    def __getattr__(self, name: str) -> Any:
+        """
+        Forward attribute access to underlying client.
+        
+        This allows access to non-chat APIs (embeddings, files, etc.)
+        without explicit wrapping.
+        """
+        return getattr(self._client, name)
+
+
+def wrap_openai(client: Any, provider: str = "openai") -> TracedOpenAI:
+    """
+    Wrap an OpenAI client for EPI tracing.
+    
+    Args:
+        client: OpenAI client instance
+        provider: Provider name for logging (default: "openai")
+        
+    Returns:
+        TracedOpenAI wrapper
+        
+    Usage:
+        from openai import OpenAI
+        from epi_recorder.wrappers import wrap_openai
+        
+        # Wrap the client once
+        client = wrap_openai(OpenAI())
+        
+        # Use normally - calls are automatically traced when inside record()
+        with record("my_agent.epi"):
+            response = client.chat.completions.create(...)
+    """
+    return TracedOpenAI(client, provider)