sequa 0.0.1__py3-none-any.whl

sequa/__init__.py

@@ -0,0 +1,2 @@
+def hello() -> str:
+    return "Hello from sequa!"

sequa/cassette.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import inspect
+import threading
+from functools import wraps
+from typing import Any, Callable, TypeVar, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from sequa.recorder import RecorderEngine
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+_local = threading.local()
+
+
+def get_active_engine() -> Any | None:
+    """Retrieve the currently active RecorderEngine from the thread-local stack."""
+    if not hasattr(_local, "stack"):
+        _local.stack = []
+    if _local.stack:
+        return _local.stack[-1]
+    return None
+
+
+class cassette:
+    def __init__(
+        self,
+        path: str = "cassettes",
+        mode: str = "auto",
+        ignore_fields: list[str] | None = None,
+        normalizer: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+        adapter: Any | None = None,
+    ) -> None:
+        self.path = path
+        self.mode = mode
+        self.ignore_fields = ignore_fields or []
+        self.normalizer = normalizer
+        self.adapter = adapter
+
+        if self.adapter is None:
+            from sequa.llm.adapters.chat import LangChainGroqAdapter
+
+            self.adapter = LangChainGroqAdapter()
+
+        from sequa.recorder import RecorderEngine
+        self.engine = RecorderEngine(
+            path=self.path,
+            mode=self.mode,
+            ignore_fields=self.ignore_fields,
+            normalizer=self.normalizer,
+        )
+        self.original_methods: list[tuple[type, str, Any]] = []
+
+    def __enter__(self) -> cassette:
+        # 1. Push self.engine onto thread-local context stack
+        if not hasattr(_local, "stack"):
+            _local.stack = []
+        _local.stack.append(self.engine)
+
+        # 2. Patch langchain_groq ChatGroq if installed
+        try:
+            from langchain_groq import ChatGroq
+
+            # Sync invoke
+            if not getattr(ChatGroq.invoke, "__sequa_patched__", False):
+                original_invoke = ChatGroq.invoke
+                self.original_methods.append((ChatGroq, "invoke", original_invoke))
+
+                def wrapped_invoke(self_obj: ChatGroq, *args: Any, **kwargs: Any) -> Any:
+                    active_engine = get_active_engine()
+                    if active_engine is None:
+                        return original_invoke(self_obj, *args, **kwargs)
+
+                    def make_live_call(s: Any, *a: Any, **kw: Any) -> Any:
+                        return original_invoke(s, *a, **kw)
+
+                    return active_engine.handle_call(self.adapter, make_live_call, self_obj, *args, **kwargs)
+
+                wrapped_invoke.__sequa_patched__ = True
+                ChatGroq.invoke = wrapped_invoke
+
+            # Async ainvoke
+            if hasattr(ChatGroq, "ainvoke"):
+                if not getattr(ChatGroq.ainvoke, "__sequa_patched__", False):
+                    original_ainvoke = ChatGroq.ainvoke
+                    self.original_methods.append((ChatGroq, "ainvoke", original_ainvoke))
+
+                    async def wrapped_ainvoke(self_obj: ChatGroq, *args: Any, **kwargs: Any) -> Any:
+                        active_engine = get_active_engine()
+                        if active_engine is None:
+                            return await original_ainvoke(self_obj, *args, **kwargs)
+
+                        async def make_live_call(s: Any, *a: Any, **kw: Any) -> Any:
+                            return await original_ainvoke(s, *a, **kw)
+
+                        return await active_engine.handle_call_async(
+                            self.adapter, make_live_call, self_obj, *args, **kwargs
+                        )
+
+                    wrapped_ainvoke.__sequa_patched__ = True
+                    ChatGroq.ainvoke = wrapped_ainvoke
+
+        except ImportError:
+            pass
+
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        # 1. Pop from stack
+        if hasattr(_local, "stack") and _local.stack:
+            _local.stack.pop()
+
+        # 2. Restore original methods
+        for cls, attr, original in self.original_methods:
+            setattr(cls, attr, original)
+        self.original_methods.clear()
+
+    def intercept(
+        self, fn: Callable[..., Any], *args: Any, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Provides direct interception utility for testing."""
+        canonical_request = self.adapter.to_canonical_request(
+            request=args[0] if args else None, **kwargs
+        )
+        result = fn(*args, **kwargs)
+        canonical_response = self.adapter.to_canonical_response(result, **kwargs)
+        return {
+            "request": canonical_request,
+            "response": canonical_response,
+            "raw": result,
+        }
+
+    def __call__(self, fn: F) -> F:
+        if inspect.iscoroutinefunction(fn):
+            @wraps(fn)
+            async def wrapped_async(*args: Any, **kwargs: Any) -> Any:
+                active_engine = get_active_engine()
+                if active_engine is not None:
+                    async def make_live_call(*a: Any, **kw: Any) -> Any:
+                        return await fn(*a, **kw)
+                    return await active_engine.handle_call_async(
+                        self.adapter, make_live_call, *args, **kwargs
+                    )
+                else:
+                    canonical_request = self.adapter.to_canonical_request(args, **kwargs)
+                    result = await fn(*args, **kwargs)
+                    canonical_response = self.adapter.to_canonical_response(result, **kwargs)
+                    return {
+                        "request": canonical_request,
+                        "response": canonical_response,
+                        "raw": result,
+                    }
+            wrapped_async.__sequa_patched__ = True
+            return wrapped_async  # type: ignore
+        else:
+            @wraps(fn)
+            def wrapped_sync(*args: Any, **kwargs: Any) -> Any:
+                active_engine = get_active_engine()
+                if active_engine is not None:
+                    def make_live_call(*a: Any, **kw: Any) -> Any:
+                        return fn(*a, **kw)
+                    return active_engine.handle_call(
+                        self.adapter, make_live_call, *args, **kwargs
+                    )
+                else:
+                    canonical_request = self.adapter.to_canonical_request(args, **kwargs)
+                    result = fn(*args, **kwargs)
+                    canonical_response = self.adapter.to_canonical_response(result, **kwargs)
+                    return {
+                        "request": canonical_request,
+                        "response": canonical_response,
+                        "raw": result,
+                    }
+            wrapped_sync.__sequa_patched__ = True
+            return wrapped_sync  # type: ignore

sequa/cli/main.py

@@ -0,0 +1,201 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from typing import Any
+
+
+def load_all_cassettes(path: str) -> list[tuple[str, dict[str, Any]]]:
+    """Finds and loads all JSON cassette files in the given directory or file path."""
+    cassettes = []
+    if os.path.isfile(path) and path.endswith(".json"):
+        try:
+            with open(path, "r", encoding="utf-8") as f:
+                cassettes.append((path, json.load(f)))
+        except Exception as e:
+            print(f"Error loading {path}: {e}", file=sys.stderr)
+    elif os.path.isdir(path):
+        for root, _, files in os.walk(path):
+            for file in files:
+                if file.endswith(".json"):
+                    file_path = os.path.join(root, file)
+                    try:
+                        with open(file_path, "r", encoding="utf-8") as f:
+                            data = json.load(f)
+                            # Simple validation to verify it is a Sequa cassette file
+                            if "request" in data and "response" in data:
+                                cassettes.append((file_path, data))
+                    except Exception as e:
+                        # Skip files that are not valid JSON or not cassettes
+                        pass
+    return cassettes
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    """Calculates and prints statistics for stored cassettes."""
+    cassettes = load_all_cassettes(args.path)
+    if not cassettes:
+        print(f"No cassettes found at path: {args.path}")
+        return 0
+
+    count = len(cassettes)
+    total_latency_ms = 0.0
+    total_size_bytes = 0
+
+    for path, data in cassettes:
+        # Size
+        try:
+            total_size_bytes += os.path.getsize(path)
+        except Exception:
+            pass
+        
+        # Latency
+        latency = data.get("metadata", {}).get("latency_ms")
+        if latency is None:
+            latency = data.get("response", {}).get("latency")
+        
+        if latency is not None:
+            try:
+                total_latency_ms += float(latency)
+            except ValueError:
+                pass
+
+    print("========================================")
+    print(" Sequa Statistics")
+    print("========================================")
+    print(f"Total Cassettes:      {count}")
+    print(f"Total Size on Disk:   {total_size_bytes / 1024:.2f} KB ({total_size_bytes} bytes)")
+    print(f"Total Latency Saved:  {total_latency_ms / 1000:.2f} seconds ({total_latency_ms:.1f} ms)")
+    print("========================================")
+    return 0
+
+
+def cmd_inspect(args: argparse.Namespace) -> int:
+    """Lists summary of all stored cassettes."""
+    cassettes = load_all_cassettes(args.path)
+    if not cassettes:
+        print(f"No cassettes found at path: {args.path}")
+        return 0
+
+    print(f"{'Filename / Hash':<40} | {'Provider':<15} | {'Model':<25} | {'Created At':<25}")
+    print("-" * 111)
+    for path, data in cassettes:
+        filename = os.path.basename(path)
+        provider = data.get("provider", "unknown")
+        
+        # Get model
+        req = data.get("request", {})
+        model = req.get("model") or "unknown"
+        
+        created_at = data.get("created_at", "unknown")
+        
+        # Format filename to fit table neatly
+        if len(filename) > 38:
+            filename_display = filename[:35] + "..."
+        else:
+            filename_display = filename
+
+        print(f"{filename_display:<40} | {provider:<15} | {model:<25} | {created_at:<25}")
+    return 0
+
+
+def cmd_clean(args: argparse.Namespace) -> int:
+    """Cleans dynamic/volatile fields from cassettes or formats them."""
+    cassettes = load_all_cassettes(args.path)
+    if not cassettes:
+        print(f"No cassettes found at path: {args.path}")
+        return 0
+
+    cleaned_count = 0
+    for path, data in cassettes:
+        modified = False
+        
+        # 1. Remove latency metadata if requested
+        if args.remove_latency:
+            if "metadata" in data and "latency_ms" in data["metadata"]:
+                del data["metadata"]["latency_ms"]
+                modified = True
+            if "response" in data and "latency" in data["response"]:
+                del data["response"]["latency"]
+                modified = True
+
+        # 2. Remove timestamps if requested
+        if args.remove_timestamps:
+            if "created_at" in data:
+                data["created_at"] = ""
+                modified = True
+
+        # 3. Format/Sort keys cleanly (always done during clean)
+        from sequa.utils import sort_dict_keys
+        data = sort_dict_keys(data)
+        modified = True
+
+        if modified:
+            try:
+                with open(path, "w", encoding="utf-8") as f:
+                    json.dump(data, f, indent=4, ensure_ascii=False)
+                cleaned_count += 1
+            except Exception as e:
+                print(f"Error writing to {path}: {e}", file=sys.stderr)
+
+    print(f"Successfully formatted/cleaned {cleaned_count} cassettes.")
+    return 0
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Sequa CLI - Manage and inspect your LLM snapshot cassettes."
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    # stats
+    parser_stats = subparsers.add_parser("stats", help="Show summary statistics of stored cassettes.")
+    parser_stats.add_argument(
+        "--path",
+        "-p",
+        default="cassettes",
+        help="Path to the cassettes directory or file (default: 'cassettes').",
+    )
+
+    # inspect
+    parser_inspect = subparsers.add_parser("inspect", help="List summary of all stored cassettes.")
+    parser_inspect.add_argument(
+        "--path",
+        "-p",
+        default="cassettes",
+        help="Path to the cassettes directory or file (default: 'cassettes').",
+    )
+
+    # clean
+    parser_clean = subparsers.add_parser("clean", help="Clean or format stored cassettes.")
+    parser_clean.add_argument(
+        "--path",
+        "-p",
+        default="cassettes",
+        help="Path to the cassettes directory or file (default: 'cassettes').",
+    )
+    parser_clean.add_argument(
+        "--remove-latency",
+        action="store_true",
+        help="Remove dynamic latency values from cassettes to avoid git diff noise.",
+    )
+    parser_clean.add_argument(
+        "--remove-timestamps",
+        action="store_true",
+        help="Redact/clear dynamic timestamps.",
+    )
+
+    args = parser.parse_args()
+
+    if args.command == "stats":
+        sys.exit(cmd_stats(args))
+    elif args.command == "inspect":
+        sys.exit(cmd_inspect(args))
+    elif args.command == "clean":
+        sys.exit(cmd_clean(args))
+
+
+if __name__ == "__main__":
+    main()

sequa/llm/adapters/__init__.py

@@ -0,0 +1,21 @@
+from .base import AdapterRegistry, ProviderAdapter, CanonicalRequest, CanonicalResponse
+from .chat import OpenAIAdapter, LangChainGroqAdapter
+from .monkey_patch import LangChainGroqMonkeyPatch
+from ...cassette import cassette
+
+
+class RequestInterceptor(cassette):
+    pass
+
+
+__all__ = [
+    "AdapterRegistry",
+    "ProviderAdapter",
+    "CanonicalRequest",
+    "CanonicalResponse",
+    "OpenAIAdapter",
+    "LangChainGroqAdapter",
+    "LangChainGroqMonkeyPatch",
+    "cassette",
+    "RequestInterceptor",
+]

sequa/llm/adapters/base.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class CanonicalRequest:
+    provider: str
+    model: str | None = None
+    messages: list[dict[str, Any]] | None = None
+    params: dict[str, Any] = field(default_factory=dict)
+    temperature: float | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class CanonicalResponse:
+    provider: str
+    output: Any = None
+    model: str | None = None
+    tool_calls: list[Any] = field(default_factory=list)
+    invalid_tool_calls: list[Any] = field(default_factory=list)
+    latency: float | None = None
+    reasoning: str | None = None
+    usage: dict[str, Any] | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class ProviderAdapter(ABC):
+    provider_name: str = ""
+
+    @abstractmethod
+    def to_canonical_request(self, request: Any, **kwargs: Any) -> CanonicalRequest:
+        """Convert a provider-specific request into the canonical request shape."""
+
+    @abstractmethod
+    def to_canonical_response(self, response: Any, **kwargs: Any) -> CanonicalResponse:
+        """Convert a provider-specific response into the canonical response shape."""
+
+    @abstractmethod
+    def from_canonical_response(self, response: CanonicalResponse, request: Any) -> Any:
+        """Rebuild a provider-native response from a canonical response."""
+
+
+class AdapterRegistry:
+    def __init__(self) -> None:
+        self._adapters: dict[str, ProviderAdapter] = {}
+
+    def register(self, adapter: ProviderAdapter) -> None:
+        self._adapters[adapter.provider_name] = adapter
+
+    def get(self, provider_name: str) -> ProviderAdapter:
+        try:
+            return self._adapters[provider_name]
+        except KeyError as exc:
+            raise KeyError(
+                f"No adapter registered for provider: {provider_name}"
+            ) from exc

sequa/llm/adapters/chat.py

@@ -0,0 +1,238 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .base import CanonicalRequest, CanonicalResponse, ProviderAdapter
+
+
+class LangChainGroqAdapter(ProviderAdapter):
+    """A generic chat-completions adapter that can be configured per provider."""
+
+    def __init__(
+        self, provider_name: str = "langchain_groq", response_object: str | None = None
+    ) -> None:
+        self.provider_name = provider_name
+        self._response_object = response_object
+
+    def to_canonical_request(self, request: Any, **kwargs: Any) -> CanonicalRequest:
+        if isinstance(request, (tuple, list)) and len(request) > 0:
+            first_arg = request[0]
+            if hasattr(first_arg, "model_name"):
+                payload = first_arg
+                messages = request[1] if len(request) > 1 else []
+            else:
+                payload = first_arg
+                messages = []
+        else:
+            payload = request or {}
+            messages = []
+
+        model = getattr(payload, "model_name", None) or kwargs.get("model")
+        temperature = getattr(payload, "temperature", None) or kwargs.get("temperature")
+
+        if isinstance(payload, dict):
+            raw_payload = payload
+            if not messages:
+                messages = payload.get("messages") or kwargs.get("messages") or []
+        else:
+            raw_payload = {"input": payload}
+            if not messages:
+                messages = kwargs.get("messages") or []
+
+        if isinstance(messages, (list, tuple)):
+            messages_list = list(messages)
+        elif messages:
+            messages_list = [messages]
+        else:
+            messages_list = []
+
+        return CanonicalRequest(
+            provider=self.provider_name,
+            model=model,
+            temperature=temperature,
+            messages=messages_list,
+            params=kwargs,
+            metadata={"raw_request": raw_payload},
+        )
+
+    def to_canonical_response(self, response: Any, **kwargs: Any) -> CanonicalResponse:
+        payload = response or {}
+        if hasattr(payload, "content") and not isinstance(payload, dict):
+            content = getattr(payload, "content", None)
+            return CanonicalResponse(
+                provider=self.provider_name,
+                output=content,
+                model=payload.response_metadata.get("model_name"),
+                tool_calls=payload.tool_calls,
+                invalid_tool_calls=payload.invalid_tool_calls,
+                latency=payload.response_metadata.get("total_time"),
+                reasoning=(
+                    payload.response_metadata.get("token_usage", {}).get("reasoning_content")
+                    if payload.response_metadata.get("token_usage")
+                    else None
+                ),
+                usage=payload.usage_metadata,
+                metadata={
+                    "raw_response": {
+                        "id": getattr(payload, "id", None),
+                        "response_metadata": getattr(payload, "response_metadata", {}),
+                    }
+                },
+            )
+
+        choices = payload.get("choices", [])
+        first_choice = choices[0] if choices else {}
+        message = first_choice.get("message", {})
+
+        return CanonicalResponse(
+            provider=self.provider_name,
+            model=kwargs.get("model"),
+            output=message.get("content"),
+            usage=payload.get("usage"),
+            metadata={"raw_response": payload},
+        )
+
+    def from_canonical_response(self, response: CanonicalResponse, request: Any) -> Any:
+        raw_resp = response.metadata.get("raw_response")
+        resp_id = "replayed-response"
+        finish_reason = "stop"
+        if raw_resp:
+            if isinstance(raw_resp, dict):
+                resp_id = raw_resp.get("id", "replayed-response")
+                choices = raw_resp.get("choices", [])
+                if choices:
+                    finish_reason = choices[0].get("finish_reason", "stop")
+            else:
+                resp_id = getattr(raw_resp, "id", "replayed-response")
+                response_metadata = getattr(raw_resp, "response_metadata", {})
+                finish_reason = response_metadata.get("finish_reason", "stop")
+
+        # Determine if we should return a LangChain AIMessage object
+        is_langchain = False
+        if request and isinstance(request, (tuple, list)) and len(request) > 0:
+            first_arg = request[0]
+            # If the class represents ChatGroq or a LangChain chat model
+            if hasattr(first_arg, "model_name") or hasattr(first_arg, "invoke"):
+                is_langchain = True
+
+        if raw_resp and hasattr(raw_resp, "content") and not isinstance(raw_resp, dict):
+            is_langchain = True
+
+        if is_langchain:
+            from langchain_core.messages import AIMessage
+            
+            response_metadata = {}
+            if raw_resp:
+                if isinstance(raw_resp, dict):
+                    response_metadata = dict(raw_resp.get("response_metadata", {}))
+                elif hasattr(raw_resp, "response_metadata"):
+                    response_metadata = dict(getattr(raw_resp, "response_metadata", {}))
+
+            if not response_metadata:
+                response_metadata = {
+                    "model_name": response.model,
+                    "finish_reason": finish_reason,
+                }
+                if response.latency is not None:
+                    response_metadata["total_time"] = response.latency
+
+            aimsg_kwargs: dict[str, Any] = {
+                "content": response.output or "",
+                "response_metadata": response_metadata,
+                "id": resp_id,
+                "tool_calls": response.tool_calls or [],
+                "invalid_tool_calls": response.invalid_tool_calls or [],
+            }
+
+            if response.usage and isinstance(response.usage, dict):
+                input_t = response.usage.get("input_tokens") or response.usage.get("prompt_tokens") or 0
+                output_t = response.usage.get("output_tokens") or response.usage.get("completion_tokens") or 0
+                total_t = response.usage.get("total_tokens") or (input_t + output_t)
+                aimsg_kwargs["usage_metadata"] = {
+                    "input_tokens": input_t,
+                    "output_tokens": output_t,
+                    "total_tokens": total_t,
+                }
+
+            return AIMessage(**aimsg_kwargs)
+
+        payload: dict[str, Any] = {
+            "id": resp_id,
+            "choices": [
+                {
+                    "message": {
+                        "role": "assistant",
+                        "content": response.output,
+                    },
+                    "finish_reason": finish_reason,
+                }
+            ],
+            "usage": response.usage or {},
+            "model": response.model or "replayed-model",
+        }
+
+        if self._response_object is not None:
+            payload["object"] = self._response_object
+
+        return payload
+
+
+class OpenAIAdapter(ProviderAdapter):
+    """An OpenAI chat completions adapter."""
+
+    def __init__(self, response_object: str | None = "chat.completion") -> None:
+        self.provider_name = "openai"
+        self._response_object = response_object
+
+    def to_canonical_request(self, request: Any, **kwargs: Any) -> CanonicalRequest:
+        payload = request or {}
+        messages = payload.get("messages", [])
+        return CanonicalRequest(
+            provider=self.provider_name,
+            model=kwargs.get("model"),
+            messages=list(messages),
+            params=kwargs,
+        )
+
+    def to_canonical_response(self, response: Any, **kwargs: Any) -> CanonicalResponse:
+        payload = response or {}
+        choices = payload.get("choices", [])
+        first_choice = choices[0] if choices else {}
+        message = first_choice.get("message", {})
+        return CanonicalResponse(
+            provider=self.provider_name,
+            model=kwargs.get("model"),
+            output=message.get("content"),
+            usage=payload.get("usage"),
+            metadata={"raw_response": payload},
+        )
+
+    def from_canonical_response(self, response: CanonicalResponse, request: Any) -> Any:
+        raw_resp = response.metadata.get("raw_response")
+        resp_id = "replayed-response"
+        finish_reason = "stop"
+        if raw_resp and isinstance(raw_resp, dict):
+            resp_id = raw_resp.get("id", "replayed-response")
+            choices = raw_resp.get("choices", [])
+            if choices:
+                finish_reason = choices[0].get("finish_reason", "stop")
+
+        payload: dict[str, Any] = {
+            "id": resp_id,
+            "choices": [
+                {
+                    "message": {
+                        "role": "assistant",
+                        "content": response.output,
+                    },
+                    "finish_reason": finish_reason,
+                }
+            ],
+            "usage": response.usage or {},
+            "model": response.model or "replayed-model",
+        }
+
+        if self._response_object is not None:
+            payload["object"] = self._response_object
+
+        return payload

sequa/llm/adapters/monkey_patch.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+class LangChainGroqMonkeyPatch:
+    def __init__(self, adapter: Any | None = None) -> None:
+        self.adapter = adapter
+        if self.adapter is None:
+            from sequa.llm.adapters.chat import LangChainGroqAdapter
+
+            self.adapter = LangChainGroqAdapter()
+        from sequa.cassette import cassette
+        self.decorator = cassette(adapter=self.adapter)
+
+    def patch(self, cls: Any) -> Any:
+        if getattr(cls.invoke, "__sequa_patched__", False):
+            return cls
+
+        original_invoke = cls.invoke
+
+        @self.decorator
+        def wrapped_invoke(self_obj: Any, *args: Any, **kwargs: Any) -> Any:
+            return original_invoke(self_obj, *args, **kwargs)
+
+        cls.invoke = wrapped_invoke
+        return cls

sequa/llm/adapters/patch_groq.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_groq import ChatGroq
+
+from sequa.cassette import cassette
+from sequa.llm.adapters.chat import LangChainGroqAdapter
+
+
+def patch_langchain(adapter: Any | None = None) -> type[ChatGroq]:
+    if getattr(ChatGroq.invoke, "__sequa_patched__", False):
+        return ChatGroq
+
+    adapter = adapter or LangChainGroqAdapter()
+    decorator = cassette(adapter=adapter)
+    original_invoke = ChatGroq.invoke
+
+    @decorator
+    def wrapped_invoke(self: ChatGroq, *args: Any, **kwargs: Any) -> Any:
+        return original_invoke(self, *args, **kwargs)
+
+    ChatGroq.invoke = wrapped_invoke
+    return ChatGroq

sequa/matcher.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+from sequa.llm.adapters.base import CanonicalRequest
+from sequa.utils import sort_dict_keys
+
+
+def normalize(req: dict[str, Any] | CanonicalRequest) -> dict[str, Any]:
+    """Normalize request into a standard dictionary structure."""
+    if isinstance(req, CanonicalRequest):
+        req_dict = {
+            "provider": req.provider,
+            "model": req.model,
+            "messages": req.messages,
+            "temperature": req.temperature,
+            "params": req.params,
+        }
+    else:
+        req_dict = dict(req)
+
+    # Normalize messages list to standard role/content/type structure
+    messages = req_dict.get("messages")
+    if messages is not None:
+        normalized_msgs = []
+        for msg in messages:
+            if isinstance(msg, dict):
+                # Keep only core message fields
+                normalized_msgs.append(
+                    {k: v for k, v in msg.items() if k in ("role", "content", "type", "name")}
+                )
+            elif hasattr(msg, "to_dict"):
+                try:
+                    d = msg.to_dict()
+                    normalized_msgs.append(
+                        {k: v for k, v in d.items() if k in ("role", "content", "type", "name")}
+                    )
+                except Exception:
+                    normalized_msgs.append({"content": str(msg)})
+            elif hasattr(msg, "dict"):
+                try:
+                    d = msg.dict()
+                    normalized_msgs.append(
+                        {k: v for k, v in d.items() if k in ("role", "content", "type", "name")}
+                    )
+                except Exception:
+                    normalized_msgs.append({"content": str(msg)})
+            else:
+                normalized_msgs.append({"content": str(msg)})
+        req_dict["messages"] = normalized_msgs
+
+    # Standardize types and remove None values to ensure consistent hashing
+    cleaned: dict[str, Any] = {}
+    for k, v in req_dict.items():
+        if v is not None:
+            if k == "params" and isinstance(v, dict):
+                # Deep clean params
+                cleaned_params = {pk: pv for pk, pv in v.items() if pv is not None}
+                cleaned[k] = cleaned_params
+            else:
+                cleaned[k] = v
+
+    return cleaned
+
+
+def hash_request(
+    req: dict[str, Any] | CanonicalRequest, ignore_fields: list[str] | None = None
+) -> str:
+    """Normalize, strip ignored fields, recursively sort, serialize, and hash a request."""
+    # 1. Normalize
+    normalized = normalize(req)
+
+    # 2. Remove ignored fields
+    ignore = ignore_fields or []
+    for field_name in ignore:
+        if field_name in normalized:
+            del normalized[field_name]
+        if "params" in normalized and isinstance(normalized["params"], dict):
+            if field_name in normalized["params"]:
+                # Copy to avoid modifying the input request dictionary in-place
+                normalized["params"] = dict(normalized["params"])
+                del normalized["params"][field_name]
+
+    # 3. Recursive sort
+    sorted_norm = sort_dict_keys(normalized)
+
+    # 4. Serialize with compact JSON notation
+    serialized = json.dumps(
+        sorted_norm, sort_keys=True, ensure_ascii=True, separators=(",", ":")
+    )
+
+    # 5. SHA-256 Hash
+    return hashlib.sha256(serialized.encode("utf-8")).hexdigest()
+
+
+def match(
+    req1: dict[str, Any] | CanonicalRequest,
+    req2: dict[str, Any] | CanonicalRequest,
+    ignore_fields: list[str] | None = None,
+) -> bool:
+    """Compare two requests to check if their hashes match after normalization and ignore filtering."""
+    return hash_request(req1, ignore_fields) == hash_request(req2, ignore_fields)

sequa/models.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import datetime
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass
+class Cassette:
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    provider: str = ""
+    hash: str = ""
+    created_at: str = field(
+        default_factory=lambda: datetime.datetime.now(datetime.timezone.utc).isoformat()
+    )
+    request: dict[str, Any] = field(default_factory=dict)
+    response: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "provider": self.provider,
+            "hash": self.hash,
+            "created_at": self.created_at,
+            "request": self.request,
+            "response": self.response,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Cassette:
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            provider=data.get("provider", ""),
+            hash=data.get("hash", ""),
+            created_at=data.get("created_at", ""),
+            request=data.get("request", {}),
+            response=data.get("response", {}),
+            metadata=data.get("metadata", {}),
+        )

sequa/recorder.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Callable
+
+from sequa.llm.adapters.base import CanonicalRequest, CanonicalResponse, ProviderAdapter
+from sequa.matcher import hash_request
+from sequa.models import Cassette
+from sequa import storage
+
+
+class SequaError(Exception):
+    """Base exception for Sequa."""
+
+
+class CassetteNotFoundError(SequaError):
+    """Exception raised when a cassette is missing in replay mode."""
+
+
+class RecorderEngine:
+    def __init__(
+        self,
+        path: str,
+        mode: str = "auto",
+        ignore_fields: list[str] | None = None,
+        normalizer: Callable[[dict[str, Any]], dict[str, Any]] | None = None,
+    ) -> None:
+        self.path = path
+        self.mode = mode.lower()
+        self.ignore_fields = ignore_fields or []
+        self.normalizer = normalizer
+
+        if self.mode not in ("replay", "record", "auto", "live"):
+            raise ValueError(f"Invalid mode: {self.mode}. Must be replay, record, auto, or live.")
+
+    def get_cassette_path(self, req_hash: str) -> str:
+        """Resolve the path to the cassette file based on request hash and configured path."""
+        # If the path is a directory (does not end in .json), append the hash filename
+        if not self.path.lower().endswith(".json"):
+            return os.path.join(self.path, f"{req_hash}.json")
+        return self.path
+
+    def handle_call(
+        self,
+        adapter: ProviderAdapter,
+        make_live_call_fn: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Intercepts the call, checking the cache according to the execution mode."""
+        # 1. Convert request args to CanonicalRequest
+        canonical_req = adapter.to_canonical_request(args, **kwargs)
+
+        # Apply custom normalizer if configured
+        if self.normalizer is not None:
+            normalized_dict = self.normalizer(
+                {
+                    "provider": canonical_req.provider,
+                    "model": canonical_req.model,
+                    "messages": canonical_req.messages,
+                    "temperature": canonical_req.temperature,
+                    "params": canonical_req.params,
+                }
+            )
+            # Rebuild canonical request from normalized dict
+            canonical_req = CanonicalRequest(
+                provider=normalized_dict.get("provider", canonical_req.provider),
+                model=normalized_dict.get("model", canonical_req.model),
+                messages=normalized_dict.get("messages", canonical_req.messages),
+                temperature=normalized_dict.get("temperature", canonical_req.temperature),
+                params=normalized_dict.get("params", canonical_req.params),
+                raw=canonical_req.raw,
+                metadata=canonical_req.metadata,
+            )
+
+        # 2. Hash request
+        req_hash = hash_request(canonical_req, self.ignore_fields)
+        cassette_path = self.get_cassette_path(req_hash)
+
+        # Mode: live
+        if self.mode == "live":
+            return make_live_call_fn(*args, **kwargs)
+
+        # Mode: replay
+        if self.mode == "replay":
+            if not storage.exists(cassette_path):
+                raise CassetteNotFoundError(
+                    f"Cassette not found in replay mode at path: {cassette_path}"
+                )
+            cassette_obj = storage.load(cassette_path)
+            canonical_resp = self._deserialize_canonical_response(cassette_obj.response)
+            return adapter.from_canonical_response(canonical_resp, args)
+
+        # Mode: auto
+        if self.mode == "auto":
+            if storage.exists(cassette_path):
+                cassette_obj = storage.load(cassette_path)
+                canonical_resp = self._deserialize_canonical_response(cassette_obj.response)
+                return adapter.from_canonical_response(canonical_resp, args)
+
+        # Mode: record, or auto on cache miss
+        start_time = time.perf_counter()
+        live_response = make_live_call_fn(*args, **kwargs)
+        latency = (time.perf_counter() - start_time) * 1000.0  # in ms
+
+        canonical_resp = adapter.to_canonical_response(live_response, **kwargs)
+        if canonical_resp.latency is None:
+            canonical_resp.latency = latency
+
+        # Serialize request/response and save to storage
+        serialized_req = self._serialize_canonical_request(canonical_req)
+        serialized_resp = self._serialize_canonical_response(canonical_resp)
+
+        cassette_obj = Cassette(
+            provider=canonical_req.provider,
+            hash=req_hash,
+            request=serialized_req,
+            response=serialized_resp,
+            metadata={"latency_ms": latency},
+        )
+        storage.save(cassette_obj, cassette_path)
+
+        return live_response
+
+    async def handle_call_async(
+        self,
+        adapter: ProviderAdapter,
+        make_live_call_fn: Callable[..., Any],
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Intercepts the async call, checking the cache according to the execution mode."""
+        # 1. Convert request args to CanonicalRequest
+        canonical_req = adapter.to_canonical_request(args, **kwargs)
+
+        # Apply custom normalizer if configured
+        if self.normalizer is not None:
+            normalized_dict = self.normalizer(
+                {
+                    "provider": canonical_req.provider,
+                    "model": canonical_req.model,
+                    "messages": canonical_req.messages,
+                    "temperature": canonical_req.temperature,
+                    "params": canonical_req.params,
+                }
+            )
+            # Rebuild canonical request from normalized dict
+            canonical_req = CanonicalRequest(
+                provider=normalized_dict.get("provider", canonical_req.provider),
+                model=normalized_dict.get("model", canonical_req.model),
+                messages=normalized_dict.get("messages", canonical_req.messages),
+                temperature=normalized_dict.get("temperature", canonical_req.temperature),
+                params=normalized_dict.get("params", canonical_req.params),
+                raw=canonical_req.raw,
+                metadata=canonical_req.metadata,
+            )
+
+        # 2. Hash request
+        req_hash = hash_request(canonical_req, self.ignore_fields)
+        cassette_path = self.get_cassette_path(req_hash)
+
+        # Mode: live
+        if self.mode == "live":
+            return await make_live_call_fn(*args, **kwargs)
+
+        # Mode: replay
+        if self.mode == "replay":
+            if not storage.exists(cassette_path):
+                raise CassetteNotFoundError(
+                    f"Cassette not found in replay mode at path: {cassette_path}"
+                )
+            cassette_obj = storage.load(cassette_path)
+            canonical_resp = self._deserialize_canonical_response(cassette_obj.response)
+            return adapter.from_canonical_response(canonical_resp, args)
+
+        # Mode: auto
+        if self.mode == "auto":
+            if storage.exists(cassette_path):
+                cassette_obj = storage.load(cassette_path)
+                canonical_resp = self._deserialize_canonical_response(cassette_obj.response)
+                return adapter.from_canonical_response(canonical_resp, args)
+
+        # Mode: record, or auto on cache miss
+        start_time = time.perf_counter()
+        live_response = await make_live_call_fn(*args, **kwargs)
+        latency = (time.perf_counter() - start_time) * 1000.0  # in ms
+
+        canonical_resp = adapter.to_canonical_response(live_response, **kwargs)
+        if canonical_resp.latency is None:
+            canonical_resp.latency = latency
+
+        # Serialize request/response and save to storage
+        serialized_req = self._serialize_canonical_request(canonical_req)
+        serialized_resp = self._serialize_canonical_response(canonical_resp)
+
+        cassette_obj = Cassette(
+            provider=canonical_req.provider,
+            hash=req_hash,
+            request=serialized_req,
+            response=serialized_resp,
+            metadata={"latency_ms": latency},
+        )
+        storage.save(cassette_obj, cassette_path)
+
+        return live_response
+
+    def _serialize_canonical_request(self, req: CanonicalRequest) -> dict[str, Any]:
+        return {
+            "provider": req.provider,
+            "model": req.model,
+            "messages": req.messages,
+            "temperature": req.temperature,
+            "params": req.params,
+        }
+
+    def _serialize_canonical_response(self, resp: CanonicalResponse) -> dict[str, Any]:
+        return {
+            "provider": resp.provider,
+            "output": resp.output,
+            "model": resp.model,
+            "tool_calls": resp.tool_calls,
+            "invalid_tool_calls": resp.invalid_tool_calls,
+            "latency": resp.latency,
+            "reasoning": resp.reasoning,
+            "usage": resp.usage,
+            "metadata": resp.metadata,
+        }
+
+    def _deserialize_canonical_response(self, data: dict[str, Any]) -> CanonicalResponse:
+        return CanonicalResponse(
+            provider=data.get("provider", ""),
+            output=data.get("output"),
+            model=data.get("model"),
+            tool_calls=data.get("tool_calls") or [],
+            invalid_tool_calls=data.get("invalid_tool_calls") or [],
+            latency=data.get("latency"),
+            reasoning=data.get("reasoning"),
+            usage=data.get("usage"),
+            metadata=data.get("metadata") or {},
+        )

sequa/storage.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from sequa.models import Cassette
+
+
+def save(cassette: Cassette, path: str) -> None:
+    """Save a cassette as a JSON file at the specified path."""
+    # Ensure directory exists
+    dir_name = os.path.dirname(path)
+    if dir_name:
+        os.makedirs(dir_name, exist_ok=True)
+    
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(cassette.to_dict(), f, indent=4, ensure_ascii=False)
+
+
+def load(path: str) -> Cassette:
+    """Load a cassette from a JSON file at the specified path."""
+    with open(path, "r", encoding="utf-8") as f:
+        data = json.load(f)
+    return Cassette.from_dict(data)
+
+
+def exists(path: str) -> bool:
+    """Check if a cassette file exists at the specified path."""
+    return os.path.isfile(path)
+
+
+def delete(path: str) -> None:
+    """Delete the cassette file at the specified path if it exists."""
+    if os.path.exists(path):
+        os.remove(path)

sequa/utils.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from typing import Any
+
+
+def sort_dict_keys(data: Any) -> Any:
+    """Recursively sort dictionary keys for deterministic hashing."""
+    if isinstance(data, dict):
+        return {k: sort_dict_keys(v) for k, v in sorted(data.items())}
+    elif isinstance(data, list):
+        return [sort_dict_keys(item) for item in data]
+    return data

sequa-0.0.1.dist-info/METADATA

@@ -0,0 +1,132 @@
+Metadata-Version: 2.3
+Name: sequa
+Version: 0.0.1
+Summary: Add your description here
+Author: thetechnoadvisor
+Author-email: thetechnoadvisor <thetechnoadvisor@gmail.com>
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: langchain-groq>=0.3.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Sequa 📼
+
+Sequa is snapshot testing for LLM applications. Record once, replay forever.
+
+---
+
+## The Magic
+
+### Before
+```python
+from langchain_groq import ChatGroq
+
+model = ChatGroq(model_name="llama-3.1-8b-instant")
+response = model.invoke("Write a 3-word slogan for gravity.")
+# ⏱️ Time taken: 2.3 seconds
+```
+
+### After
+```python
+from langchain_groq import ChatGroq
+from sequa import cassette
+
+model = ChatGroq(model_name="llama-3.1-8b-instant")
+
+with cassette("tests/cassettes"):
+    response = model.invoke("Write a 3-word slogan for gravity.")
+    # ⏱️ First run: 2.3 seconds (recorded to tests/cassettes/)
+    # ⏱️ Second run: 12 ms (replayed locally!)
+```
+
+---
+
+## Features
+
+- **Record once, replay forever**: Speed up integration test suites from minutes to milliseconds.
+- **Multiple Execution Modes**: Support `replay`, `record`, `auto`, and `live` modes.
+- **Robust Key Sorting & Hashing**: Recursively sorts request inputs to generate deterministic hashes.
+- **Custom Ignored Fields**: Easily ignore dynamic/unstable fields (e.g. `temperature`, `max_tokens`).
+- **Custom Normalizers**: Redact, replace, or clean requests prior to hashing.
+- **CLI Utilities**: Inspect, format, and calculate statistics of stored cassettes.
+
+---
+
+## Installation
+
+```bash
+uv pip install -e .
+```
+
+---
+
+## Configuration & Advanced API
+
+### 1. Execution Modes
+
+Control Sequa behavior via the `mode` parameter:
+
+```python
+with cassette("tests/cassettes", mode="replay"):
+    # Will raise CassetteNotFoundError if no matching cassette is found.
+    # Guaranteed to make zero external network requests.
+```
+
+- `auto` (Default): Replays if a matching cassette exists, otherwise calls the live API and records it.
+- `record`: Always calls the live API and records/overwrites the cassette.
+- `replay`: Never calls the live API. Raises `CassetteNotFoundError` on cache misses.
+- `live`: Direct pass-through to the live API, bypassing cassettes entirely.
+
+### 2. Ignore Fields
+
+Strip request parameters before generating hashes:
+
+```python
+with cassette("tests/cassettes", ignore_fields=["temperature", "max_tokens"]):
+    # These two calls generate the exact same hash and match the same cassette:
+    model.invoke("hello", temperature=0.2)
+    model.invoke("hello", temperature=0.9)
+```
+
+### 3. Custom Normalizers
+
+For complex normalization or content redaction:
+
+```python
+def redact_dates(request_dict):
+    # Redact dynamic inputs or strip timestamps
+    return request_dict
+
+with cassette("tests/cassettes", normalizer=redact_dates):
+    model.invoke(...)
+```
+
+---
+
+## Command Line Interface (CLI)
+
+Sequa comes with a CLI tool to manage your cassettes.
+
+### Stats
+Show the number of cassettes, total size on disk, and estimated API latency saved:
+```bash
+sequa stats --path ./tests/cassettes
+```
+
+### Inspect
+List all stored cassettes, their model, provider, and when they were recorded:
+```bash
+sequa inspect --path ./tests/cassettes
+```
+
+### Clean
+Clean dynamic fields (`latency`, `created_at`) from cassettes to prevent noisy git diffs:
+```bash
+sequa clean --path ./tests/cassettes --remove-latency --remove-timestamps
+```
+
+---
+
+## License
+
+MIT License.

sequa-0.0.1.dist-info/RECORD

@@ -0,0 +1,18 @@
+sequa/__init__.py,sha256=radOQ-iUQ98KHoBPX-981_1dTxCFfNO3gk2YeUKKWsE,51
+sequa/cassette.py,sha256=zNpejzSnHNwO2hOyh0IyvpUEFyxc9f0AMwMFBnyNPvg,6811
+sequa/cli/main.py,sha256=6w9esnNDcmT8JMgWZs9iMIpdgtrgn915LGKfEGYOmGc,6757
+sequa/llm/adapters/__init__.py,sha256=sbzm9VWXkG9zVLBE5DPjZ1b2y1x1cJkBv1ENhQVe0QY,507
+sequa/llm/adapters/base.py,sha256=lq5EMVnQOrItLercPn8IYPtzltqntDhVcOAnVSt5h5U,2025
+sequa/llm/adapters/chat.py,sha256=LNElOqCvckobKBUr131cLYuRLB1LDx39qoT8LIWVLJY,9247
+sequa/llm/adapters/monkey_patch.py,sha256=eujopQF_wRChZXBqXF7AzNQtPoysWo8Ag8aSN8R8g8M,816
+sequa/llm/adapters/patch_groq.py,sha256=MofDcr0M5U-yCn5CwYyv9FQqghyYUBNI-nzDRDVlwzI,675
+sequa/matcher.py,sha256=30fgPZYZ2e3_wdQVi0inAtc1eq4YoDGhgCK6vX7cJ8k,3779
+sequa/models.py,sha256=uvB6-910-BPYi-fdEOC3vFLTxoDChv7798qjf4jRQ5M,1326
+sequa/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sequa/recorder.py,sha256=Htja5CG99fyGE3pY-KTNPRjtPGYXzkRUp-y92OBQLtU,9606
+sequa/storage.py,sha256=NlmFT-UmW3m59vpXVq2AiHmjm_JtBoQ6ZeKTdJL1qw4,986
+sequa/utils.py,sha256=aYUGyfEqcQimGXLYYULIVgdh3_Ck2O8bh3R3ThKNtZ4,375
+sequa-0.0.1.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+sequa-0.0.1.dist-info/entry_points.txt,sha256=xoYq4KZ0oJYxFU2PPH530SVsRNBilkhyF0ErZftrez4,47
+sequa-0.0.1.dist-info/METADATA,sha256=kkbeWL0fYNHgKEU5fcD-l7aq381wQneW6oGE_DPMmoM,3471
+sequa-0.0.1.dist-info/RECORD,,

sequa-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.9.28
+Root-Is-Purelib: true
+Tag: py3-none-any

sequa-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+sequa = sequa.cli.main:main
+