sequa 0.0.1__tar.gz

sequa-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,121 @@
+# 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/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "sequa"
+version = "0.0.1"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "thetechnoadvisor", email = "thetechnoadvisor@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "python-dotenv>=1.0.0",
+    "langchain-groq>=0.3.0",
+]
+
+[project.scripts]
+sequa = "sequa.cli.main:main"
+
+[build-system]
+requires = ["uv_build>=0.9.28,<0.10.0"]
+build-backend = "uv_build"

sequa-0.0.1/src/sequa/__init__.py

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

sequa-0.0.1/src/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-0.0.1/src/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-0.0.1/src/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",
+]