From 692bc528e39b35a1b91bafe7c22fe37330dfe46f Mon Sep 17 00:00:00 2001
From: Kesavaraja M <krkesavaraja67@gmail.com>
Date: Thu, 15 Jan 2026 17:26:08 +0530
Subject: [PATCH 1/7] feat: implement JIT benchmarking suite and comparison
 logic

---
 cortex/cli.py               |  61 +++++
 cortex/jit_benchmark.py     | 525 ++++++++++++++++++++++++++++++++++++
 tests/test_jit_benchmark.py | 320 ++++++++++++++++++++++
 3 files changed, 906 insertions(+)
 create mode 100644 cortex/jit_benchmark.py
 create mode 100644 tests/test_jit_benchmark.py

diff --git a/cortex/cli.py b/cortex/cli.py
index e8afb525..f301cda3 100644
--- a/cortex/cli.py
+++ b/cortex/cli.py
@@ -23,6 +23,7 @@
 )
 from cortex.env_manager import EnvironmentManager, get_env_manager
 from cortex.installation_history import InstallationHistory, InstallationStatus, InstallationType
+from cortex.jit_benchmark import run_jit_benchmark
 from cortex.llm.interpreter import CommandInterpreter
 from cortex.network_config import NetworkConfig
 from cortex.notification_manager import NotificationManager
@@ -768,6 +769,30 @@ def _sandbox_exec(self, sandbox, args: argparse.Namespace) -> int:
 
     # --- End Sandbox Commands ---
 
+    def jit_benchmark(self, args: argparse.Namespace) -> int:
+        """Handle JIT benchmarking commands.
+
+        Args:
+            args: Parsed command-line arguments.
+
+        Returns:
+            Exit code (0 for success, 1 for error).
+        """
+        action = getattr(args, "bench_action", "run")
+        benchmark_name = getattr(args, "benchmark", None)
+        iterations = getattr(args, "iterations", 100)
+        output = getattr(args, "output", None)
+
+        # Handle compare action
+        if action == "compare":
+            baseline = getattr(args, "baseline", None)
+            jit = getattr(args, "jit", None)
+            return run_jit_benchmark(action="compare", compare_baseline=baseline, compare_jit=jit)
+
+        return run_jit_benchmark(
+            action=action, benchmark_name=benchmark_name, iterations=iterations, output=output
+        )
+
     def ask(self, question: str) -> int:
         """Answer a natural language question about the system."""
         api_key = self._get_api_key()
@@ -2207,6 +2232,7 @@ def show_rich_help():
     table.add_row("env", "Manage environment variables")
     table.add_row("cache stats", "Show LLM cache statistics")
     table.add_row("docker permissions", "Fix Docker bind-mount permissions")
+    table.add_row("jit-benchmark", "Python JIT performance benchmarks")
     table.add_row("sandbox <cmd>", "Test packages in Docker sandbox")
     table.add_row("doctor", "System health check")
 
@@ -2277,6 +2303,36 @@ def main():
     docker_parser = subparsers.add_parser("docker", help="Docker and container utilities")
     docker_subs = docker_parser.add_subparsers(dest="docker_action", help="Docker actions")
 
+    # JIT Benchmark command
+    jit_parser = subparsers.add_parser(
+        "jit-benchmark", help="Benchmark Python JIT compilation performance"
+    )
+    jit_subs = jit_parser.add_subparsers(dest="bench_action", help="Benchmark actions")
+
+    # jit-benchmark run (default action)
+    jit_run_parser = jit_subs.add_parser("run", help="Run benchmarks")
+    jit_run_parser.add_argument(
+        "-b",
+        "--benchmark",
+        choices=["cli", "parse", "cache", "stream"],
+        help="Specific benchmark to run (default: all)",
+    )
+    jit_run_parser.add_argument(
+        "-i", "--iterations", type=int, default=100, help="Number of iterations (default: 100)"
+    )
+    jit_run_parser.add_argument("-o", "--output", help="Export results to JSON file")
+
+    # jit-benchmark list
+    jit_subs.add_parser("list", help="List available benchmarks")
+
+    # jit-benchmark info
+    jit_subs.add_parser("info", help="Show JIT status and information")
+
+    # jit-benchmark compare
+    jit_compare_parser = jit_subs.add_parser("compare", help="Compare baseline vs JIT results")
+    jit_compare_parser.add_argument("--baseline", required=True, help="Baseline results JSON file")
+    jit_compare_parser.add_argument("--jit", required=True, help="JIT results JSON file")
+
     # Add the permissions action to allow fixing file ownership issues
     perm_parser = docker_subs.add_parser(
         "permissions", help="Fix file permissions from bind mounts"
@@ -2702,6 +2758,11 @@ def main():
                 dry_run=args.dry_run,
                 parallel=args.parallel,
             )
+        elif args.command == "jit-benchmark":
+            # Set default action if no subcommand
+            if not hasattr(args, "bench_action") or args.bench_action is None:
+                args.bench_action = "run"
+            return cli.jit_benchmark(args)
         elif args.command == "import":
             return cli.import_deps(args)
         elif args.command == "history":
diff --git a/cortex/jit_benchmark.py b/cortex/jit_benchmark.py
new file mode 100644
index 00000000..65421d72
--- /dev/null
+++ b/cortex/jit_benchmark.py
@@ -0,0 +1,525 @@
+"""JIT Compiler Benchmarking for Cortex Operations.
+
+This module provides comprehensive performance benchmarking for Python 3.13+
+experimental JIT compilation. It measures CLI startup, command parsing,
+cache operations, and response streaming performance.
+
+"""
+
+import json
+import os
+import statistics
+import sys
+import time
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+
+
+class BenchmarkCategory(Enum):
+    """Categories of benchmarks."""
+
+    STARTUP = "startup"
+    PARSING = "parsing"
+    CACHE = "cache"
+    STREAMING = "streaming"
+
+
+@dataclass
+class BenchmarkResult:
+    """Results from a single benchmark run."""
+
+    name: str
+    category: BenchmarkCategory
+    mean: float
+    median: float
+    stdev: float
+    min_time: float
+    max_time: float
+    iterations: int
+    jit_enabled: bool
+
+    def to_dict(self) -> dict:
+        """Convert to dictionary for JSON export."""
+        return {
+            "name": self.name,
+            "category": self.category.value,
+            "mean": self.mean,
+            "median": self.median,
+            "stdev": self.stdev,
+            "min": self.min_time,
+            "max": self.max_time,
+            "iterations": self.iterations,
+            "jit_enabled": self.jit_enabled,
+        }
+
+
+@dataclass
+class BenchmarkComparison:
+    """Comparison between two benchmark results."""
+
+    name: str
+    baseline_time: float
+    jit_time: float
+    speedup: float
+    percent_improvement: float
+
+    @property
+    def is_faster(self) -> bool:
+        """Check if JIT version is faster."""
+        return self.speedup > 1.0
+
+
+class JITBenchmark:
+    """Main benchmarking class for Cortex operations."""
+
+    def __init__(self, iterations: int = 100):
+        """Initialize benchmarker.
+
+        Args:
+            iterations: Number of times to run each benchmark.
+        """
+        self.iterations = iterations
+        self.jit_enabled = self._detect_jit()
+        self.results: list[BenchmarkResult] = []
+
+    def _detect_jit(self) -> bool:
+        """Detect if Python JIT is enabled.
+
+        Returns:
+            True if JIT is enabled, False otherwise.
+        """
+        # Python 3.13+ has PYTHON_JIT environment variable
+        return os.environ.get("PYTHON_JIT", "0") == "1"
+
+    def _format_time(self, seconds: float) -> str:
+        """Format time in appropriate unit.
+
+        Args:
+            seconds: Time in seconds.
+
+        Returns:
+            Formatted time string.
+        """
+        if seconds >= 1.0:
+            return f"{seconds:.4f}s"
+        elif seconds >= 0.001:
+            return f"{seconds * 1000:.2f}ms"
+        else:
+            return f"{seconds * 1_000_000:.2f}μs"
+
+    def _run_benchmark(
+        self, func: Callable, name: str, category: BenchmarkCategory
+    ) -> BenchmarkResult:
+        """Run a single benchmark.
+
+        Args:
+            func: Function to benchmark.
+            name: Name of the benchmark.
+            category: Category of the benchmark.
+
+        Returns:
+            BenchmarkResult with timing statistics.
+        """
+        times = []
+
+        # Warmup run
+        func()
+
+        # Actual benchmark runs
+        for _ in range(self.iterations):
+            start = time.perf_counter()
+            func()
+            end = time.perf_counter()
+            times.append(end - start)
+
+        return BenchmarkResult(
+            name=name,
+            category=category,
+            mean=statistics.mean(times),
+            median=statistics.median(times),
+            stdev=statistics.stdev(times) if len(times) > 1 else 0.0,
+            min_time=min(times),
+            max_time=max(times),
+            iterations=self.iterations,
+            jit_enabled=self.jit_enabled,
+        )
+
+    def _bench_cli_startup(self) -> None:
+        """Benchmark CLI startup time."""
+        # Simulate CLI initialization overhead
+        import argparse
+
+        parser = argparse.ArgumentParser()
+        parser.add_argument("command")
+        parser.add_argument("--execute", action="store_true")
+        _ = parser.parse_args(["install", "--execute"])
+
+    def _bench_command_parsing(self) -> None:
+        """Benchmark command parsing."""
+        # Simulate command parsing logic
+        commands = [
+            "install nginx",
+            "update system",
+            "search python3-pip",
+            "remove old-package",
+        ]
+
+        for cmd in commands:
+            parts = cmd.split()
+            action = parts[0] if parts else ""
+            args = parts[1:] if len(parts) > 1 else []
+            # Simulate parsing logic
+            _ = {"action": action, "args": args}
+
+    def _bench_cache_operations(self) -> None:
+        """Benchmark cache read/write operations."""
+        # Simulate cache operations
+        cache_data = {f"key_{i}": f"value_{i}" * 10 for i in range(100)}
+
+        # Write
+        for key, value in cache_data.items():
+            _ = json.dumps({key: value})
+
+        # Read
+        for key in cache_data:
+            _ = cache_data.get(key)
+
+    def _bench_response_streaming(self) -> None:
+        """Benchmark response streaming."""
+        # Simulate streaming response processing
+        response = "This is a test response " * 100
+        chunk_size = 50
+        chunks = [response[i : i + chunk_size] for i in range(0, len(response), chunk_size)]
+
+        for chunk in chunks:
+            # Simulate chunk processing
+            _ = chunk.upper().lower()
+
+    def run_all_benchmarks(self) -> list[BenchmarkResult]:
+        """Run all benchmarks.
+
+        Returns:
+            List of BenchmarkResult objects.
+        """
+        benchmarks = [
+            ("CLI Startup", BenchmarkCategory.STARTUP, self._bench_cli_startup),
+            ("Command Parsing", BenchmarkCategory.PARSING, self._bench_command_parsing),
+            ("Cache Operations", BenchmarkCategory.CACHE, self._bench_cache_operations),
+            ("Response Streaming", BenchmarkCategory.STREAMING, self._bench_response_streaming),
+        ]
+
+        self.results = []
+
+        for name, category, func in benchmarks:
+            console.print(f"[cyan]Benchmarking {name}...[/cyan]")
+            result = self._run_benchmark(func, name, category)
+            self.results.append(result)
+
+        return self.results
+
+    def run_benchmark(self, benchmark_name: str) -> BenchmarkResult | None:
+        """Run a specific benchmark.
+
+        Args:
+            benchmark_name: Name of benchmark to run.
+
+        Returns:
+            BenchmarkResult or None if not found.
+        """
+        benchmark_map = {
+            "cli": ("CLI Startup", BenchmarkCategory.STARTUP, self._bench_cli_startup),
+            "parse": ("Command Parsing", BenchmarkCategory.PARSING, self._bench_command_parsing),
+            "cache": ("Cache Operations", BenchmarkCategory.CACHE, self._bench_cache_operations),
+            "stream": (
+                "Response Streaming",
+                BenchmarkCategory.STREAMING,
+                self._bench_response_streaming,
+            ),
+        }
+
+        if benchmark_name not in benchmark_map:
+            return None
+
+        name, category, func = benchmark_map[benchmark_name]
+        console.print(f"[cyan]Benchmarking {name}...[/cyan]")
+        result = self._run_benchmark(func, name, category)
+        self.results.append(result)
+        return result
+
+    def list_benchmarks(self) -> list[str]:
+        """List available benchmarks.
+
+        Returns:
+            List of benchmark names.
+        """
+        return ["cli", "parse", "cache", "stream"]
+
+    def display_results(self) -> None:
+        """Display benchmark results in a formatted table."""
+        if not self.results:
+            console.print("[yellow]No benchmark results to display[/yellow]")
+            return
+
+        table = Table(
+            title="Cortex JIT Benchmark Results", show_header=True, header_style="bold cyan"
+        )
+        table.add_column("Benchmark", style="green", width=20)
+        table.add_column("Mean", justify="right")
+        table.add_column("Median", justify="right")
+        table.add_column("Std Dev", justify="right")
+        table.add_column("Min", justify="right")
+        table.add_column("Max", justify="right")
+
+        for result in self.results:
+            table.add_row(
+                result.name,
+                self._format_time(result.mean),
+                self._format_time(result.median),
+                self._format_time(result.stdev),
+                self._format_time(result.min_time),
+                self._format_time(result.max_time),
+            )
+
+        console.print()
+        console.print(table)
+        console.print()
+        console.print(f"[dim]Python {sys.version_info.major}.{sys.version_info.minor}[/dim]")
+        console.print(f"[dim]JIT: {'Enabled' if self.jit_enabled else 'Disabled'}[/dim]")
+
+    def export_json(self, filepath: str) -> None:
+        """Export results to JSON file.
+
+        Args:
+            filepath: Path to output JSON file.
+        """
+        data = {
+            "metadata": {
+                "python_version": f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}",
+                "jit_enabled": self.jit_enabled,
+                "iterations": self.iterations,
+                "timestamp": time.time(),
+            },
+            "results": [r.to_dict() for r in self.results],
+        }
+
+        with open(filepath, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2)
+
+        console.print(f"[green]✓[/green] Results exported to {filepath}")
+
+    def generate_recommendations(self) -> None:
+        """Generate performance recommendations based on results."""
+        if not self.results:
+            return
+
+        console.print("\n[bold]Recommendations:[/bold]")
+
+        if self.jit_enabled:
+            console.print("[green]✓[/green] JIT compilation is enabled - performance gains active")
+        else:
+            if sys.version_info >= (3, 13):
+                console.print(
+                    "[yellow]ℹ[/yellow] Enable JIT for potential speedups: export PYTHON_JIT=1"
+                )
+            else:
+                console.print(
+                    "[yellow]ℹ[/yellow] Upgrade to Python 3.13+ for JIT compilation support"
+                )
+
+        # Analyze results
+        slow_benchmarks = [r for r in self.results if r.mean > 0.01]  # > 10ms
+        if slow_benchmarks:
+            console.print(
+                f"\n[yellow]Performance hotspots detected in {len(slow_benchmarks)} operation(s):[/yellow]"
+            )
+            for bench in slow_benchmarks:
+                console.print(f"  • {bench.name}: {self._format_time(bench.mean)}")
+
+
+def compare_results(baseline_file: str, jit_file: str) -> None:
+    """Compare benchmark results between baseline and JIT.
+
+    Args:
+        baseline_file: Path to baseline JSON results.
+        jit_file: Path to JIT-enabled JSON results.
+    """
+    with open(baseline_file, encoding="utf-8") as f:
+        baseline_data = json.load(f)
+
+    with open(jit_file, encoding="utf-8") as f:
+        jit_data = json.load(f)
+
+    # Create comparison table
+    table = Table(title="JIT Performance Comparison", show_header=True, header_style="bold cyan")
+    table.add_column("Benchmark", style="green")
+    table.add_column("Baseline", justify="right")
+    table.add_column("With JIT", justify="right")
+    table.add_column("Speedup", justify="right")
+    table.add_column("Improvement", justify="right")
+
+    comparisons: list[BenchmarkComparison] = []
+
+    baseline_results = {r["name"]: r for r in baseline_data["results"]}
+    jit_results = {r["name"]: r for r in jit_data["results"]}
+
+    for name in baseline_results:
+        if name not in jit_results:
+            continue
+
+        baseline_time = baseline_results[name]["mean"]
+        jit_time = jit_results[name]["mean"]
+
+        speedup = baseline_time / jit_time if jit_time > 0 else 0
+        improvement = ((baseline_time - jit_time) / baseline_time * 100) if baseline_time > 0 else 0
+
+        comp = BenchmarkComparison(
+            name=name,
+            baseline_time=baseline_time,
+            jit_time=jit_time,
+            speedup=speedup,
+            percent_improvement=improvement,
+        )
+        comparisons.append(comp)
+
+        # Format times
+        def fmt(t):
+            if t >= 1.0:
+                return f"{t:.4f}s"
+            elif t >= 0.001:
+                return f"{t * 1000:.2f}ms"
+            else:
+                return f"{t * 1_000_000:.2f}μs"
+
+        speedup_str = f"{speedup:.2f}x" if speedup > 0 else "N/A"
+
+        improvement_color = "green" if improvement > 0 else "red"
+        improvement_str = f"[{improvement_color}]{improvement:+.1f}%[/{improvement_color}]"
+
+        table.add_row(name, fmt(baseline_time), fmt(jit_time), speedup_str, improvement_str)
+
+    console.print()
+    console.print(table)
+
+    # Summary
+    if comparisons:
+        avg_improvement = statistics.mean([c.percent_improvement for c in comparisons])
+        console.print()
+        console.print(f"[bold]Average Performance Change:[/bold] {avg_improvement:+.1f}%")
+
+        if avg_improvement > 5:
+            console.print("[green]✓ JIT provides significant performance benefit[/green]")
+        elif avg_improvement > 0:
+            console.print("[yellow]ℹ JIT provides modest performance benefit[/yellow]")
+        else:
+            console.print("[red]⚠ JIT does not improve performance[/red]")
+
+
+def show_jit_info() -> None:
+    """Display JIT availability and status information."""
+    console.print("\n[bold cyan]Python JIT Information[/bold cyan]")
+    console.print(
+        f"Python version: {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+    )
+
+    jit_available = sys.version_info >= (3, 13)
+    jit_enabled = os.environ.get("PYTHON_JIT", "0") == "1"
+
+    if jit_available:
+        console.print("[green]✓[/green] JIT compilation available (Python 3.13+)")
+    else:
+        console.print("[yellow]✗[/yellow] JIT compilation not available (requires Python 3.13+)")
+
+    if jit_enabled:
+        console.print("[green]✓[/green] JIT compilation is ENABLED")
+    else:
+        console.print("[yellow]✗[/yellow] JIT compilation is DISABLED")
+
+    if jit_available and not jit_enabled:
+        console.print("\n[dim]To enable JIT: export PYTHON_JIT=1[/dim]")
+        console.print("[dim]Then run benchmarks again to compare[/dim]")
+
+
+def run_jit_benchmark(
+    action: str = "run",
+    benchmark_name: str | None = None,
+    iterations: int = 100,
+    output: str | None = None,
+    compare_baseline: str | None = None,
+    compare_jit: str | None = None,
+) -> int:
+    """Run JIT benchmarking suite.
+
+    Args:
+        action: Action to perform (run, list, info).
+        benchmark_name: Specific benchmark to run (None for all).
+        iterations: Number of iterations per benchmark.
+        output: Output file for JSON export.
+        compare_baseline: Baseline results file for comparison.
+        compare_jit: JIT results file for comparison.
+
+    Returns:
+        Exit code (0 for success, 1 for error).
+    """
+    if action == "info":
+        show_jit_info()
+        return 0
+
+    if action == "compare":
+        if not compare_baseline or not compare_jit:
+            console.print("[red]Error: --compare requires both --baseline and --jit files[/red]")
+            return 1
+
+        try:
+            compare_results(compare_baseline, compare_jit)
+            return 0
+        except FileNotFoundError as e:
+            console.print(f"[red]Error: {e}[/red]")
+            return 1
+        except json.JSONDecodeError as e:
+            console.print(f"[red]Error parsing JSON: {e}[/red]")
+            return 1
+
+    benchmarker = JITBenchmark(iterations=iterations)
+
+    if action == "list":
+        console.print("\n[bold cyan]Available Benchmarks:[/bold cyan]")
+        for bench in benchmarker.list_benchmarks():
+            console.print(f"  • {bench}")
+        console.print("\n[dim]Run: cortex jit-benchmark -b <name>[/dim]")
+        return 0
+
+    # Run benchmarks
+    console.print(
+        f"\n[bold cyan]Running Cortex JIT Benchmarks[/bold cyan] ({iterations} iterations)"
+    )
+    console.print(f"Python {sys.version_info.major}.{sys.version_info.minor} | ", end="")
+    console.print(f"JIT: {'Enabled' if benchmarker.jit_enabled else 'Disabled'}")
+    console.print()
+
+    if benchmark_name:
+        result = benchmarker.run_benchmark(benchmark_name)
+        if not result:
+            console.print(f"[red]Error: Unknown benchmark '{benchmark_name}'[/red]")
+            console.print("Run 'cortex jit-benchmark list' to see available benchmarks")
+            return 1
+    else:
+        benchmarker.run_all_benchmarks()
+
+    # Display results
+    benchmarker.display_results()
+
+    # Generate recommendations
+    benchmarker.generate_recommendations()
+
+    # Export if requested
+    if output:
+        benchmarker.export_json(output)
+
+    return 0
diff --git a/tests/test_jit_benchmark.py b/tests/test_jit_benchmark.py
new file mode 100644
index 00000000..4dc22e32
--- /dev/null
+++ b/tests/test_jit_benchmark.py
@@ -0,0 +1,320 @@
+"""Tests for JIT benchmark module."""
+
+import json
+import os
+import tempfile
+from unittest.mock import patch
+
+import pytest
+
+from cortex.jit_benchmark import (
+    BenchmarkCategory,
+    BenchmarkComparison,
+    BenchmarkResult,
+    JITBenchmark,
+    compare_results,
+    run_jit_benchmark,
+    show_jit_info,
+)
+
+
+class TestBenchmarkResult:
+    """Tests for BenchmarkResult dataclass."""
+
+    def test_to_dict(self):
+        """Test conversion to dictionary."""
+        result = BenchmarkResult(
+            name="Test Benchmark",
+            category=BenchmarkCategory.STARTUP,
+            mean=0.001,
+            median=0.0009,
+            stdev=0.0001,
+            min_time=0.0008,
+            max_time=0.0012,
+            iterations=100,
+            jit_enabled=True,
+        )
+
+        data = result.to_dict()
+
+        assert data["name"] == "Test Benchmark"
+        assert data["category"] == "startup"
+        assert data["mean"] == 0.001
+        assert data["jit_enabled"] is True
+
+
+class TestBenchmarkComparison:
+    """Tests for BenchmarkComparison dataclass."""
+
+    def test_is_faster_true(self):
+        """Test is_faster when JIT is faster."""
+        comp = BenchmarkComparison(
+            name="Test",
+            baseline_time=0.002,
+            jit_time=0.001,
+            speedup=2.0,
+            percent_improvement=50.0,
+        )
+        assert comp.is_faster is True
+
+    def test_is_faster_false(self):
+        """Test is_faster when JIT is slower."""
+        comp = BenchmarkComparison(
+            name="Test",
+            baseline_time=0.001,
+            jit_time=0.002,
+            speedup=0.5,
+            percent_improvement=-50.0,
+        )
+        assert comp.is_faster is False
+
+
+class TestJITBenchmark:
+    """Tests for JITBenchmark class."""
+
+    def test_init(self):
+        """Test initialization."""
+        bench = JITBenchmark(iterations=50)
+        assert bench.iterations == 50
+        assert isinstance(bench.jit_enabled, bool)
+        assert bench.results == []
+
+    @patch.dict(os.environ, {"PYTHON_JIT": "1"})
+    def test_detect_jit_enabled(self):
+        """Test JIT detection when enabled."""
+        bench = JITBenchmark()
+        assert bench.jit_enabled is True
+
+    @patch.dict(os.environ, {"PYTHON_JIT": "0"})
+    def test_detect_jit_disabled(self):
+        """Test JIT detection when disabled."""
+        bench = JITBenchmark()
+        assert bench.jit_enabled is False
+
+    def test_format_time_seconds(self):
+        """Test time formatting for seconds."""
+        bench = JITBenchmark()
+        assert "s" in bench._format_time(1.5)
+
+    def test_format_time_milliseconds(self):
+        """Test time formatting for milliseconds."""
+        bench = JITBenchmark()
+        assert "ms" in bench._format_time(0.005)
+
+    def test_format_time_microseconds(self):
+        """Test time formatting for microseconds."""
+        bench = JITBenchmark()
+        assert "μs" in bench._format_time(0.0000005)
+
+    def test_bench_cli_startup(self):
+        """Test CLI startup benchmark runs without error."""
+        bench = JITBenchmark(iterations=5)
+        bench._bench_cli_startup()  # Should not raise
+
+    def test_bench_command_parsing(self):
+        """Test command parsing benchmark runs without error."""
+        bench = JITBenchmark(iterations=5)
+        bench._bench_command_parsing()  # Should not raise
+
+    def test_bench_cache_operations(self):
+        """Test cache operations benchmark runs without error."""
+        bench = JITBenchmark(iterations=5)
+        bench._bench_cache_operations()  # Should not raise
+
+    def test_bench_response_streaming(self):
+        """Test response streaming benchmark runs without error."""
+        bench = JITBenchmark(iterations=5)
+        bench._bench_response_streaming()  # Should not raise
+
+    def test_run_benchmark(self):
+        """Test running a single benchmark."""
+        bench = JITBenchmark(iterations=5)
+        result = bench.run_benchmark("cli")
+
+        assert result is not None
+        assert result.name == "CLI Startup"
+        assert result.category == BenchmarkCategory.STARTUP
+        assert result.iterations == 5
+        assert result.mean > 0
+
+    def test_run_benchmark_invalid(self):
+        """Test running an invalid benchmark."""
+        bench = JITBenchmark()
+        result = bench.run_benchmark("nonexistent")
+        assert result is None
+
+    def test_run_all_benchmarks(self):
+        """Test running all benchmarks."""
+        bench = JITBenchmark(iterations=5)
+        results = bench.run_all_benchmarks()
+
+        assert len(results) == 4
+        assert all(isinstance(r, BenchmarkResult) for r in results)
+        assert all(r.iterations == 5 for r in results)
+
+    def test_list_benchmarks(self):
+        """Test listing available benchmarks."""
+        bench = JITBenchmark()
+        benchmarks = bench.list_benchmarks()
+
+        assert "cli" in benchmarks
+        assert "parse" in benchmarks
+        assert "cache" in benchmarks
+        assert "stream" in benchmarks
+
+    def test_export_json(self):
+        """Test exporting results to JSON."""
+        bench = JITBenchmark(iterations=5)
+        bench.run_all_benchmarks()
+
+        with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".json") as f:
+            filepath = f.name
+
+        try:
+            bench.export_json(filepath)
+
+            with open(filepath, encoding="utf-8") as f:
+                data = json.load(f)
+
+            assert "metadata" in data
+            assert "results" in data
+            assert data["metadata"]["iterations"] == 5
+            assert len(data["results"]) == 4
+        finally:
+            os.unlink(filepath)
+
+    def test_display_results_empty(self):
+        """Test displaying results when no benchmarks run."""
+        bench = JITBenchmark()
+        bench.display_results()  # Should not raise
+
+    def test_display_results_with_data(self):
+        """Test displaying results with benchmark data."""
+        bench = JITBenchmark(iterations=5)
+        bench.run_all_benchmarks()
+        bench.display_results()  # Should not raise
+
+    def test_generate_recommendations(self):
+        """Test generating recommendations."""
+        bench = JITBenchmark(iterations=5)
+        bench.run_all_benchmarks()
+        bench.generate_recommendations()  # Should not raise
+
+
+def test_compare_results():
+    """Test comparing baseline and JIT results."""
+    # Create temporary JSON files
+    baseline_data = {
+        "metadata": {"python_version": "3.13.0", "jit_enabled": False},
+        "results": [
+            {
+                "name": "CLI Startup",
+                "category": "startup",
+                "mean": 0.002,
+                "median": 0.0019,
+                "stdev": 0.0001,
+                "min": 0.0018,
+                "max": 0.0022,
+                "iterations": 100,
+                "jit_enabled": False,
+            }
+        ],
+    }
+
+    jit_data = {
+        "metadata": {"python_version": "3.13.0", "jit_enabled": True},
+        "results": [
+            {
+                "name": "CLI Startup",
+                "category": "startup",
+                "mean": 0.001,
+                "median": 0.0009,
+                "stdev": 0.00005,
+                "min": 0.0009,
+                "max": 0.0011,
+                "iterations": 100,
+                "jit_enabled": True,
+            }
+        ],
+    }
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix="_baseline.json") as baseline_f:
+        json.dump(baseline_data, baseline_f)
+        baseline_path = baseline_f.name
+
+    with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix="_jit.json") as jit_f:
+        json.dump(jit_data, jit_f)
+        jit_path = jit_f.name
+
+    try:
+        compare_results(baseline_path, jit_path)  # Should not raise
+    finally:
+        os.unlink(baseline_path)
+        os.unlink(jit_path)
+
+
+def test_show_jit_info():
+    """Test displaying JIT information."""
+    show_jit_info()  # Should not raise
+
+
+class TestRunJITBenchmark:
+    """Tests for run_jit_benchmark function."""
+
+    def test_run_info_action(self):
+        """Test info action."""
+        result = run_jit_benchmark(action="info")
+        assert result == 0
+
+    def test_run_list_action(self):
+        """Test list action."""
+        result = run_jit_benchmark(action="list")
+        assert result == 0
+
+    def test_run_all_benchmarks(self):
+        """Test running all benchmarks."""
+        result = run_jit_benchmark(action="run", iterations=5)
+        assert result == 0
+
+    def test_run_specific_benchmark(self):
+        """Test running a specific benchmark."""
+        result = run_jit_benchmark(action="run", benchmark_name="cli", iterations=5)
+        assert result == 0
+
+    def test_run_invalid_benchmark(self):
+        """Test running an invalid benchmark."""
+        result = run_jit_benchmark(action="run", benchmark_name="nonexistent", iterations=5)
+        assert result == 1
+
+    def test_run_with_export(self):
+        """Test running benchmarks with JSON export."""
+        with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".json") as f:
+            output_path = f.name
+
+        try:
+            result = run_jit_benchmark(action="run", iterations=5, output=output_path)
+            assert result == 0
+            assert os.path.exists(output_path)
+
+            with open(output_path, encoding="utf-8") as f:
+                data = json.load(f)
+
+            assert "metadata" in data
+            assert "results" in data
+        finally:
+            if os.path.exists(output_path):
+                os.unlink(output_path)
+
+    def test_compare_missing_files(self):
+        """Test compare action with missing files."""
+        result = run_jit_benchmark(
+            action="compare",
+            compare_baseline="nonexistent_baseline.json",
+            compare_jit="nonexistent_jit.json",
+        )
+        assert result == 1
+
+    def test_compare_without_files(self):
+        """Test compare action without file arguments."""
+        result = run_jit_benchmark(action="compare")
+        assert result == 1

From 8a610fe354071bc94847d11aaf522e34dbd240ed Mon Sep 17 00:00:00 2001
From: Kesavaraja M <krkesavaraja67@gmail.com>
Date: Thu, 15 Jan 2026 18:49:34 +0530
Subject: [PATCH 2/7] refactor: address AI review feedback and improve
 benchmark robustness

---
 cortex/jit_benchmark.py     | 163 ++++++++++++------------------------
 tests/test_jit_benchmark.py |   3 +-
 2 files changed, 56 insertions(+), 110 deletions(-)

diff --git a/cortex/jit_benchmark.py b/cortex/jit_benchmark.py
index 65421d72..fa88a72e 100644
--- a/cortex/jit_benchmark.py
+++ b/cortex/jit_benchmark.py
@@ -3,7 +3,6 @@
 This module provides comprehensive performance benchmarking for Python 3.13+
 experimental JIT compilation. It measures CLI startup, command parsing,
 cache operations, and response streaming performance.
-
 """
 
 import json
@@ -14,13 +13,26 @@
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Optional
+from typing import Any
 
 from rich.console import Console
 from rich.table import Table
 
 console = Console()
 
+SLOW_BENCHMARK_THRESHOLD_S = 0.01
+SIGNIFICANT_IMPROVEMENT_THRESHOLD_PERCENT = 5.0
+
+
+def format_benchmark_time(seconds: float) -> str:
+    """Utility to format time units consistently across the module."""
+    if seconds >= 1.0:
+        return f"{seconds:.4f}s"
+    elif seconds >= 0.001:
+        return f"{seconds * 1000:.2f}ms"
+    else:
+        return f"{seconds * 1_000_000:.2f}μs"
+
 
 class BenchmarkCategory(Enum):
     """Categories of benchmarks."""
@@ -81,7 +93,6 @@ class JITBenchmark:
 
     def __init__(self, iterations: int = 100):
         """Initialize benchmarker.
-
         Args:
             iterations: Number of times to run each benchmark.
         """
@@ -91,7 +102,6 @@ def __init__(self, iterations: int = 100):
 
     def _detect_jit(self) -> bool:
         """Detect if Python JIT is enabled.
-
         Returns:
             True if JIT is enabled, False otherwise.
         """
@@ -100,45 +110,33 @@ def _detect_jit(self) -> bool:
 
     def _format_time(self, seconds: float) -> str:
         """Format time in appropriate unit.
-
         Args:
             seconds: Time in seconds.
-
         Returns:
             Formatted time string.
         """
-        if seconds >= 1.0:
-            return f"{seconds:.4f}s"
-        elif seconds >= 0.001:
-            return f"{seconds * 1000:.2f}ms"
-        else:
-            return f"{seconds * 1_000_000:.2f}μs"
+        return format_benchmark_time(seconds)
 
     def _run_benchmark(
         self, func: Callable, name: str, category: BenchmarkCategory
     ) -> BenchmarkResult:
         """Run a single benchmark.
-
         Args:
             func: Function to benchmark.
             name: Name of the benchmark.
             category: Category of the benchmark.
-
         Returns:
             BenchmarkResult with timing statistics.
         """
         times = []
-
         # Warmup run
         func()
-
         # Actual benchmark runs
         for _ in range(self.iterations):
             start = time.perf_counter()
             func()
             end = time.perf_counter()
             times.append(end - start)
-
         return BenchmarkResult(
             name=name,
             category=category,
@@ -170,7 +168,6 @@ def _bench_command_parsing(self) -> None:
             "search python3-pip",
             "remove old-package",
         ]
-
         for cmd in commands:
             parts = cmd.split()
             action = parts[0] if parts else ""
@@ -182,11 +179,9 @@ def _bench_cache_operations(self) -> None:
         """Benchmark cache read/write operations."""
         # Simulate cache operations
         cache_data = {f"key_{i}": f"value_{i}" * 10 for i in range(100)}
-
         # Write
         for key, value in cache_data.items():
             _ = json.dumps({key: value})
-
         # Read
         for key in cache_data:
             _ = cache_data.get(key)
@@ -197,14 +192,12 @@ def _bench_response_streaming(self) -> None:
         response = "This is a test response " * 100
         chunk_size = 50
         chunks = [response[i : i + chunk_size] for i in range(0, len(response), chunk_size)]
-
         for chunk in chunks:
             # Simulate chunk processing
             _ = chunk.upper().lower()
 
     def run_all_benchmarks(self) -> list[BenchmarkResult]:
         """Run all benchmarks.
-
         Returns:
             List of BenchmarkResult objects.
         """
@@ -214,22 +207,17 @@ def run_all_benchmarks(self) -> list[BenchmarkResult]:
             ("Cache Operations", BenchmarkCategory.CACHE, self._bench_cache_operations),
             ("Response Streaming", BenchmarkCategory.STREAMING, self._bench_response_streaming),
         ]
-
         self.results = []
-
         for name, category, func in benchmarks:
             console.print(f"[cyan]Benchmarking {name}...[/cyan]")
             result = self._run_benchmark(func, name, category)
             self.results.append(result)
-
         return self.results
 
     def run_benchmark(self, benchmark_name: str) -> BenchmarkResult | None:
         """Run a specific benchmark.
-
         Args:
             benchmark_name: Name of benchmark to run.
-
         Returns:
             BenchmarkResult or None if not found.
         """
@@ -243,10 +231,8 @@ def run_benchmark(self, benchmark_name: str) -> BenchmarkResult | None:
                 self._bench_response_streaming,
             ),
         }
-
         if benchmark_name not in benchmark_map:
             return None
-
         name, category, func = benchmark_map[benchmark_name]
         console.print(f"[cyan]Benchmarking {name}...[/cyan]")
         result = self._run_benchmark(func, name, category)
@@ -255,7 +241,6 @@ def run_benchmark(self, benchmark_name: str) -> BenchmarkResult | None:
 
     def list_benchmarks(self) -> list[str]:
         """List available benchmarks.
-
         Returns:
             List of benchmark names.
         """
@@ -266,7 +251,6 @@ def display_results(self) -> None:
         if not self.results:
             console.print("[yellow]No benchmark results to display[/yellow]")
             return
-
         table = Table(
             title="Cortex JIT Benchmark Results", show_header=True, header_style="bold cyan"
         )
@@ -276,7 +260,6 @@ def display_results(self) -> None:
         table.add_column("Std Dev", justify="right")
         table.add_column("Min", justify="right")
         table.add_column("Max", justify="right")
-
         for result in self.results:
             table.add_row(
                 result.name,
@@ -286,7 +269,6 @@ def display_results(self) -> None:
                 self._format_time(result.min_time),
                 self._format_time(result.max_time),
             )
-
         console.print()
         console.print(table)
         console.print()
@@ -295,7 +277,6 @@ def display_results(self) -> None:
 
     def export_json(self, filepath: str) -> None:
         """Export results to JSON file.
-
         Args:
             filepath: Path to output JSON file.
         """
@@ -308,19 +289,15 @@ def export_json(self, filepath: str) -> None:
             },
             "results": [r.to_dict() for r in self.results],
         }
-
         with open(filepath, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=2)
-
         console.print(f"[green]✓[/green] Results exported to {filepath}")
 
     def generate_recommendations(self) -> None:
         """Generate performance recommendations based on results."""
         if not self.results:
             return
-
         console.print("\n[bold]Recommendations:[/bold]")
-
         if self.jit_enabled:
             console.print("[green]✓[/green] JIT compilation is enabled - performance gains active")
         else:
@@ -332,9 +309,8 @@ def generate_recommendations(self) -> None:
                 console.print(
                     "[yellow]ℹ[/yellow] Upgrade to Python 3.13+ for JIT compilation support"
                 )
-
         # Analyze results
-        slow_benchmarks = [r for r in self.results if r.mean > 0.01]  # > 10ms
+        slow_benchmarks = [r for r in self.results if r.mean > SLOW_BENCHMARK_THRESHOLD_S]  # > 10ms
         if slow_benchmarks:
             console.print(
                 f"\n[yellow]Performance hotspots detected in {len(slow_benchmarks)} operation(s):[/yellow]"
@@ -345,17 +321,14 @@ def generate_recommendations(self) -> None:
 
 def compare_results(baseline_file: str, jit_file: str) -> None:
     """Compare benchmark results between baseline and JIT.
-
     Args:
         baseline_file: Path to baseline JSON results.
         jit_file: Path to JIT-enabled JSON results.
     """
     with open(baseline_file, encoding="utf-8") as f:
         baseline_data = json.load(f)
-
     with open(jit_file, encoding="utf-8") as f:
         jit_data = json.load(f)
-
     # Create comparison table
     table = Table(title="JIT Performance Comparison", show_header=True, header_style="bold cyan")
     table.add_column("Benchmark", style="green")
@@ -363,22 +336,16 @@ def compare_results(baseline_file: str, jit_file: str) -> None:
     table.add_column("With JIT", justify="right")
     table.add_column("Speedup", justify="right")
     table.add_column("Improvement", justify="right")
-
     comparisons: list[BenchmarkComparison] = []
-
-    baseline_results = {r["name"]: r for r in baseline_data["results"]}
-    jit_results = {r["name"]: r for r in jit_data["results"]}
-
+    baseline_results = {r["name"]: r for r in baseline_data.get("results", [])}
+    jit_results = {r["name"]: r for r in jit_data.get("results", [])}
     for name in baseline_results:
         if name not in jit_results:
             continue
-
         baseline_time = baseline_results[name]["mean"]
         jit_time = jit_results[name]["mean"]
-
         speedup = baseline_time / jit_time if jit_time > 0 else 0
         improvement = ((baseline_time - jit_time) / baseline_time * 100) if baseline_time > 0 else 0
-
         comp = BenchmarkComparison(
             name=name,
             baseline_time=baseline_time,
@@ -387,33 +354,24 @@ def compare_results(baseline_file: str, jit_file: str) -> None:
             percent_improvement=improvement,
         )
         comparisons.append(comp)
-
-        # Format times
-        def fmt(t):
-            if t >= 1.0:
-                return f"{t:.4f}s"
-            elif t >= 0.001:
-                return f"{t * 1000:.2f}ms"
-            else:
-                return f"{t * 1_000_000:.2f}μs"
-
         speedup_str = f"{speedup:.2f}x" if speedup > 0 else "N/A"
-
         improvement_color = "green" if improvement > 0 else "red"
         improvement_str = f"[{improvement_color}]{improvement:+.1f}%[/{improvement_color}]"
-
-        table.add_row(name, fmt(baseline_time), fmt(jit_time), speedup_str, improvement_str)
-
+        table.add_row(
+            name,
+            format_benchmark_time(baseline_time),
+            format_benchmark_time(jit_time),
+            speedup_str,
+            improvement_str,
+        )
     console.print()
     console.print(table)
-
     # Summary
     if comparisons:
         avg_improvement = statistics.mean([c.percent_improvement for c in comparisons])
         console.print()
         console.print(f"[bold]Average Performance Change:[/bold] {avg_improvement:+.1f}%")
-
-        if avg_improvement > 5:
+        if avg_improvement > SIGNIFICANT_IMPROVEMENT_THRESHOLD_PERCENT:
             console.print("[green]✓ JIT provides significant performance benefit[/green]")
         elif avg_improvement > 0:
             console.print("[yellow]ℹ JIT provides modest performance benefit[/yellow]")
@@ -427,20 +385,16 @@ def show_jit_info() -> None:
     console.print(
         f"Python version: {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
     )
-
     jit_available = sys.version_info >= (3, 13)
     jit_enabled = os.environ.get("PYTHON_JIT", "0") == "1"
-
     if jit_available:
         console.print("[green]✓[/green] JIT compilation available (Python 3.13+)")
     else:
         console.print("[yellow]✗[/yellow] JIT compilation not available (requires Python 3.13+)")
-
     if jit_enabled:
         console.print("[green]✓[/green] JIT compilation is ENABLED")
     else:
         console.print("[yellow]✗[/yellow] JIT compilation is DISABLED")
-
     if jit_available and not jit_enabled:
         console.print("\n[dim]To enable JIT: export PYTHON_JIT=1[/dim]")
         console.print("[dim]Then run benchmarks again to compare[/dim]")
@@ -455,7 +409,6 @@ def run_jit_benchmark(
     compare_jit: str | None = None,
 ) -> int:
     """Run JIT benchmarking suite.
-
     Args:
         action: Action to perform (run, list, info).
         benchmark_name: Specific benchmark to run (None for all).
@@ -463,63 +416,55 @@ def run_jit_benchmark(
         output: Output file for JSON export.
         compare_baseline: Baseline results file for comparison.
         compare_jit: JIT results file for comparison.
-
     Returns:
         Exit code (0 for success, 1 for error).
     """
     if action == "info":
         show_jit_info()
         return 0
-
     if action == "compare":
-        if not compare_baseline or not compare_jit:
-            console.print("[red]Error: --compare requires both --baseline and --jit files[/red]")
-            return 1
-
-        try:
-            compare_results(compare_baseline, compare_jit)
-            return 0
-        except FileNotFoundError as e:
-            console.print(f"[red]Error: {e}[/red]")
-            return 1
-        except json.JSONDecodeError as e:
-            console.print(f"[red]Error parsing JSON: {e}[/red]")
-            return 1
+        return _handle_compare_action(compare_baseline, compare_jit)
+    if action == "list":
+        return _handle_list_action()
+    return _execute_benchmark_run(iterations, benchmark_name, output)
 
-    benchmarker = JITBenchmark(iterations=iterations)
 
-    if action == "list":
-        console.print("\n[bold cyan]Available Benchmarks:[/bold cyan]")
-        for bench in benchmarker.list_benchmarks():
-            console.print(f"  • {bench}")
-        console.print("\n[dim]Run: cortex jit-benchmark -b <name>[/dim]")
+def _handle_compare_action(baseline: str | None, jit: str | None) -> int:
+    if not baseline or not jit:
+        console.print("[red]Error: --compare requires both --baseline and --jit files[/red]")
+        return 1
+    try:
+        compare_results(baseline, jit)
         return 0
+    except (FileNotFoundError, json.JSONDecodeError) as e:
+        console.print(f"[red]Error: {e}[/red]")
+        return 1
+
 
-    # Run benchmarks
+def _handle_list_action() -> int:
+    benchmarker = JITBenchmark()
+    console.print("\n[bold cyan]Available Benchmarks:[/bold cyan]")
+    for bench in benchmarker.list_benchmarks():
+        console.print(f"  • {bench}")
+    return 0
+
+
+def _execute_benchmark_run(iterations: int, name: str | None, output: str | None) -> int:
+    benchmarker = JITBenchmark(iterations=iterations)
     console.print(
         f"\n[bold cyan]Running Cortex JIT Benchmarks[/bold cyan] ({iterations} iterations)"
     )
     console.print(f"Python {sys.version_info.major}.{sys.version_info.minor} | ", end="")
-    console.print(f"JIT: {'Enabled' if benchmarker.jit_enabled else 'Disabled'}")
-    console.print()
-
-    if benchmark_name:
-        result = benchmarker.run_benchmark(benchmark_name)
+    console.print(f"JIT: {'Enabled' if benchmarker.jit_enabled else 'Disabled'}\n")
+    if name:
+        result = benchmarker.run_benchmark(name)
         if not result:
-            console.print(f"[red]Error: Unknown benchmark '{benchmark_name}'[/red]")
-            console.print("Run 'cortex jit-benchmark list' to see available benchmarks")
+            console.print(f"[red]Error: Unknown benchmark '{name}'[/red]")
             return 1
     else:
         benchmarker.run_all_benchmarks()
-
-    # Display results
     benchmarker.display_results()
-
-    # Generate recommendations
     benchmarker.generate_recommendations()
-
-    # Export if requested
     if output:
         benchmarker.export_json(output)
-
     return 0
diff --git a/tests/test_jit_benchmark.py b/tests/test_jit_benchmark.py
index 4dc22e32..3ae1e297 100644
--- a/tests/test_jit_benchmark.py
+++ b/tests/test_jit_benchmark.py
@@ -6,6 +6,7 @@
 from unittest.mock import patch
 
 import pytest
+from pytest import approx
 
 from cortex.jit_benchmark import (
     BenchmarkCategory,
@@ -39,7 +40,7 @@ def test_to_dict(self):
 
         assert data["name"] == "Test Benchmark"
         assert data["category"] == "startup"
-        assert data["mean"] == 0.001
+        assert data["mean"] == approx(0.001)
         assert data["jit_enabled"] is True
 
 

From 4cdadfad6ddf37b95f48f4baa1e4799ffe580445 Mon Sep 17 00:00:00 2001
From: Kesavaraja M <krkesavaraja67@gmail.com>
Date: Thu, 15 Jan 2026 19:35:22 +0530
Subject: [PATCH 3/7] chore: Added Documentation

---
 docs/JIT_BENCHMARK.md | 108 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)
 create mode 100644 docs/JIT_BENCHMARK.md

diff --git a/docs/JIT_BENCHMARK.md b/docs/JIT_BENCHMARK.md
new file mode 100644
index 00000000..74e66433
--- /dev/null
+++ b/docs/JIT_BENCHMARK.md
@@ -0,0 +1,108 @@
+# 🚀 Cortex JIT Benchmarking Suite
+
+The **Cortex JIT Benchmarking Suite** is a specialized performance analysis tool designed to measure and compare the impact of the **Python 3.13+ Experimental JIT (Just-In-Time) compiler** on core Cortex operations.
+
+As Cortex moves toward supporting modern Python features, this suite provides developers with empirical data to identify performance hotspots and quantify the speedups provided by JIT compilation.
+
+---
+
+## 🛠 Command Reference
+
+The suite is fully integrated into the `cortex` CLI. Use the following commands to manage and run your benchmarks.
+
+### 1. Environment Status
+
+Check if your current system supports JIT and verify if it is currently active.
+
+```bash
+cortex jit-benchmark info
+```
+
+### 2. Available Tests
+
+List the specific benchmark categories available for execution.
+
+```bash
+cortex jit-benchmark list
+```
+
+### 3. Execution
+
+Run the full suite or target specific operations.
+
+```bash
+# Run all benchmarks with default (100) iterations
+cortex jit-benchmark run
+
+# Run a specific benchmark (cli, parse, cache, or stream)
+cortex jit-benchmark run -b cache
+
+# Customize precision with iterations
+cortex jit-benchmark run -i 500
+
+# Export results for comparison
+cortex jit-benchmark run -o baseline_results.json
+```
+
+### 4. Comparison
+
+Compare two sets of results (e.g., Baseline vs. JIT) to calculate speedup percentages.
+
+```bash
+cortex jit-benchmark compare --baseline baseline.json --jit jit_enabled.json
+```
+
+---
+
+## 📊 Benchmark Categories
+
+| Category | Method | Description |
+|----------|--------|-------------|
+| CLI Startup | _bench_cli_startup | Measures argparse initialization and CLI entry-point routing latency. |
+| Command Parsing | _bench_command_parsing | Benchmarks the splitting and interpretation of complex natural language commands. |
+| Cache Operations | _bench_cache_operations | Tests JSON serialization/deserialization and retrieval speed of the semantic cache. |
+| Response Streaming | _bench_response_streaming | Simulates high-volume processing of LLM response chunks and string manipulation. |
+
+---
+
+## 🧪 Statistical Methodology
+
+To ensure accuracy and scientific rigor, the suite employs the following logic:
+
+- **Warmup Phase**: Every benchmark function is executed once before timing starts to ensure the CPU cache is primed and the JIT profiler has observed the code path.
+- **Iterative Measurement**: Functions are run $N$ times using `time.perf_counter()` for high-resolution timing.
+- **Metrics**:
+  - **Mean**: The average execution time.
+  - **Median**: The middle value (resistant to outliers).
+  - **Std Dev**: Measures the consistency and jitter of the performance.
+  - **Min/Max**: Identifies the best and worst-case scenarios.
+- **Speedup Calculation**:
+
+$$ \text{Speedup} = \frac{\text{Baseline Time}}{\text{JIT Time}} $$
+
+$$ \text{Improvement %} = \left( \frac{\text{Baseline} - \text{JIT}}{\text{Baseline}} \right) \times 100 $$
+
+---
+
+## 💡 Enabling JIT for Testing
+
+To see actual performance gains, you must be using Python 3.13 or newer. Python JIT is experimental and must be enabled via environment variables:
+
+```bash
+# Enable JIT in your current session
+export PYTHON_JIT=1
+
+# Verify activation
+cortex jit-benchmark info
+
+# Run benchmarks
+cortex jit-benchmark run
+```
+
+---
+
+## 📝 Technical Notes
+
+- **JSON Export**: Standardized JSON format allows for cross-system performance audits and historical tracking.
+- **Precision Safety**: The test suite (`tests/test_jit_benchmark.py`) uses `pytest.approx()` for all floating-point comparisons to handle micro-second timing drift across different hardware.
+- **Modular Architecture**: The implementation uses a "routing" pattern in `cli.py` to keep the core CLI logic clean while supporting complex benchmarking subcommands.
\ No newline at end of file

From 7196d14c2ad58c70a6841505ac0f1989bf03ec24 Mon Sep 17 00:00:00 2001
From: Kesavaraja M <krkesavaraja67@gmail.com>
Date: Thu, 15 Jan 2026 19:42:06 +0530
Subject: [PATCH 4/7] docs: add JIT benchmarking documentation and update main
 README

---
 README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.md b/README.md
index 37407191..81dde917 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,7 @@ cortex install "tools for video compression"
 | **Full Rollback** | Undo any installation with `cortex rollback` |
 | **Role Management** | AI-driven system personality detection and tailored recommendations |
 | **Docker Permission Fixer** | Fix root-owned bind mount issues automatically |
+| **JIT Benchmarking** | Measure Python 3.13 performance gains for Cortex operations |
 | **Audit Trail** | Complete history in `~/.cortex/history.db` |
 | **Hardware-Aware** | Detects GPU, CPU, memory for optimized packages |
 | **Multi-LLM Support** | Works with Claude, GPT-4, or local Ollama models |
@@ -177,6 +178,18 @@ cortex role detect
 cortex role set <slug>
 ```
 
+### JIT Benchmarking (Python 3.13+)
+
+Measure the speed impact of Python's new JIT compiler on Cortex:
+
+```bash
+# Run all benchmarks
+cortex jit-benchmark run
+
+# Compare a non-JIT baseline with a JIT-enabled run
+cortex jit-benchmark compare --baseline base.json --jit enabled.json
+```
+
 ### Command Reference
 
 | Command | Description |
@@ -187,6 +200,7 @@ cortex role set <slug>
 | `cortex docker permissions` | Fix file ownership for Docker bind mounts |
 | `cortex role detect` | Automatically identifies the system's purpose |
 | `cortex role set <slug>` | Manually declare a system role |
+| `cortex jit-benchmark` | Run Python 3.13+ JIT performance benchmarks |
 | `cortex sandbox <cmd>` | Test packages in Docker sandbox |
 | `cortex history` | View all past installations |
 | `cortex rollback <id>` | Undo a specific installation |
@@ -378,6 +392,7 @@ pip install -e .
 - [x] Dry-run preview mode
 - [x] Docker bind-mount permission fixer
 - [x] Automatic Role Discovery (AI-driven system context sensing)
+- [x] Python JIT Benchmarking Suite (Performance analysis)
 
 ### In Progress
 - [ ] Conflict resolution UI

From 8f13d0cf5bff7f492524bb7dcf03c1ce9983f5ca Mon Sep 17 00:00:00 2001
From: Kesavaraja M <krkesavaraja67@gmail.com>
Date: Thu, 15 Jan 2026 19:56:09 +0530
Subject: [PATCH 5/7] docs: complete jit-benchmark documentation per
 gemini-code-assist feedback

---
 README.md             | 12 ++++++++----
 docs/JIT_BENCHMARK.md | 33 +++++++++++----------------------
 2 files changed, 19 insertions(+), 26 deletions(-)

diff --git a/README.md b/README.md
index 81dde917..2e38f061 100644
--- a/README.md
+++ b/README.md
@@ -183,10 +183,14 @@ cortex role set <slug>
 Measure the speed impact of Python's new JIT compiler on Cortex:
 
 ```bash
-# Run all benchmarks
-cortex jit-benchmark run
+# Check status and list tests
+cortex jit-benchmark info
+cortex jit-benchmark list
 
-# Compare a non-JIT baseline with a JIT-enabled run
+# Run with custom iterations and export
+cortex jit-benchmark run --iterations 50 --output results.json
+
+# Compare results
 cortex jit-benchmark compare --baseline base.json --jit enabled.json
 ```
 
@@ -200,7 +204,7 @@ cortex jit-benchmark compare --baseline base.json --jit enabled.json
 | `cortex docker permissions` | Fix file ownership for Docker bind mounts |
 | `cortex role detect` | Automatically identifies the system's purpose |
 | `cortex role set <slug>` | Manually declare a system role |
-| `cortex jit-benchmark` | Run Python 3.13+ JIT performance benchmarks |
+| `cortex jit-benchmark <subcommand>` | Run, compare, and analyze Python 3.13+ JIT performance benchmarks |
 | `cortex sandbox <cmd>` | Test packages in Docker sandbox |
 | `cortex history` | View all past installations |
 | `cortex rollback <id>` | Undo a specific installation |
diff --git a/docs/JIT_BENCHMARK.md b/docs/JIT_BENCHMARK.md
index 74e66433..a707b21f 100644
--- a/docs/JIT_BENCHMARK.md
+++ b/docs/JIT_BENCHMARK.md
@@ -8,11 +8,9 @@ As Cortex moves toward supporting modern Python features, this suite provides de
 
 ## 🛠 Command Reference
 
-The suite is fully integrated into the `cortex` CLI. Use the following commands to manage and run your benchmarks.
+### 1. Environment Information
 
-### 1. Environment Status
-
-Check if your current system supports JIT and verify if it is currently active.
+Show Python JIT status and system compatibility.
 
 ```bash
 cortex jit-benchmark info
@@ -20,36 +18,27 @@ cortex jit-benchmark info
 
 ### 2. Available Tests
 
-List the specific benchmark categories available for execution.
+List all specific benchmark categories supported by the current version.
 
 ```bash
 cortex jit-benchmark list
 ```
 
-### 3. Execution
-
-Run the full suite or target specific operations.
+### 3. Running Benchmarks
 
-```bash
-# Run all benchmarks with default (100) iterations
-cortex jit-benchmark run
+The `run` subcommand supports several parameters for granular testing:
 
-# Run a specific benchmark (cli, parse, cache, or stream)
-cortex jit-benchmark run -b cache
-
-# Customize precision with iterations
-cortex jit-benchmark run -i 500
-
-# Export results for comparison
-cortex jit-benchmark run -o baseline_results.json
-```
+- **Default Run**: `cortex jit-benchmark run`
+- **Custom Iterations**: `cortex jit-benchmark run --iterations 50`
+- **Specific Category**: `cortex jit-benchmark run --benchmark cli` (Choices: `cli`, `parse`, `cache`, `stream`)
+- **Export Data**: `cortex jit-benchmark run --output results.json`
 
 ### 4. Comparison
 
-Compare two sets of results (e.g., Baseline vs. JIT) to calculate speedup percentages.
+Compare a baseline result against a JIT-enabled result.
 
 ```bash
-cortex jit-benchmark compare --baseline baseline.json --jit jit_enabled.json
+cortex jit-benchmark compare --baseline base.json --jit enabled.json
 ```
 
 ---

From 8a931c8fbbbdfd90d77c33781499a3207a22b052 Mon Sep 17 00:00:00 2001
From: "autofix-ci[bot]" <114827586+autofix-ci[bot]@users.noreply.github.com>
Date: Fri, 16 Jan 2026 03:19:30 +0000
Subject: [PATCH 6/7] [autofix.ci] apply automated fixes

---
 tests/test_licensing.py | 51 ++++++++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 18 deletions(-)

diff --git a/tests/test_licensing.py b/tests/test_licensing.py
index def55e4a..68f64c21 100644
--- a/tests/test_licensing.py
+++ b/tests/test_licensing.py
@@ -1,26 +1,27 @@
 """Tests for cortex/licensing.py - License management and feature gating."""
 
 import json
-import pytest
-from datetime import datetime, timezone, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from unittest.mock import patch, MagicMock
+from unittest.mock import MagicMock, patch
+
+import pytest
 
 from cortex.licensing import (
+    FEATURE_NAMES,
+    FEATURE_REQUIREMENTS,
+    LICENSE_FILE,
+    FeatureNotAvailableError,
     FeatureTier,
     LicenseInfo,
-    FEATURE_REQUIREMENTS,
-    FEATURE_NAMES,
+    _get_hostname,
+    activate_license,
+    check_feature,
     get_license_info,
     get_license_tier,
-    check_feature,
     require_feature,
-    activate_license,
     show_license_status,
     show_upgrade_prompt,
-    FeatureNotAvailableError,
-    LICENSE_FILE,
-    _get_hostname,
 )
 
 
@@ -143,19 +144,20 @@ class TestGetLicenseInfo:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
 
     def test_returns_license_info(self):
         """Should return LicenseInfo object."""
-        with patch.object(Path, 'exists', return_value=False):
+        with patch.object(Path, "exists", return_value=False):
             info = get_license_info()
             assert isinstance(info, LicenseInfo)
 
     def test_default_community_tier(self):
         """Should default to community tier when no license file."""
-        with patch.object(Path, 'exists', return_value=False):
+        with patch.object(Path, "exists", return_value=False):
             info = get_license_info()
             assert info.tier == FeatureTier.COMMUNITY
 
@@ -174,14 +176,14 @@ def test_reads_license_file(self, tmp_path):
         license_file = tmp_path / "license.key"
         license_file.write_text(json.dumps(license_data))
 
-        with patch.object(lic, 'LICENSE_FILE', license_file):
+        with patch.object(lic, "LICENSE_FILE", license_file):
             info = get_license_info()
             assert info.tier == "pro"
             assert info.organization == "Test Org"
 
     def test_caches_result(self):
         """Should cache license info."""
-        with patch.object(Path, 'exists', return_value=False):
+        with patch.object(Path, "exists", return_value=False):
             info1 = get_license_info()
             info2 = get_license_info()
             assert info1 is info2
@@ -194,6 +196,7 @@ class TestCheckFeature:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -201,6 +204,7 @@ def reset_cache(self):
     def test_community_features_allowed(self):
         """Community tier should access community features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         # Unknown features default to community
@@ -209,6 +213,7 @@ def test_community_features_allowed(self):
     def test_pro_feature_blocked_for_community(self):
         """Community tier should not access pro features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         assert check_feature("cloud_llm", silent=True) is False
@@ -216,6 +221,7 @@ def test_pro_feature_blocked_for_community(self):
     def test_pro_feature_allowed_for_pro(self):
         """Pro tier should access pro features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.PRO)
 
         assert check_feature("cloud_llm", silent=True) is True
@@ -223,6 +229,7 @@ def test_pro_feature_allowed_for_pro(self):
     def test_enterprise_feature_allowed_for_enterprise(self):
         """Enterprise tier should access all features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.ENTERPRISE)
 
         assert check_feature("sso", silent=True) is True
@@ -231,6 +238,7 @@ def test_enterprise_feature_allowed_for_enterprise(self):
     def test_shows_upgrade_prompt(self, capsys):
         """Should show upgrade prompt when feature blocked."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         check_feature("cloud_llm", silent=False)
@@ -245,6 +253,7 @@ class TestRequireFeatureDecorator:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -252,6 +261,7 @@ def reset_cache(self):
     def test_allows_when_feature_available(self):
         """Should allow function call when feature available."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.PRO)
 
         @require_feature("cloud_llm")
@@ -263,6 +273,7 @@ def test_func():
     def test_raises_when_feature_blocked(self):
         """Should raise FeatureNotAvailableError when feature blocked."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         @require_feature("cloud_llm")
@@ -297,6 +308,7 @@ class TestActivateLicense:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -314,8 +326,8 @@ def test_successful_activation(self, tmp_path):
             "organization": "Test Org",
         }
 
-        with patch.object(lic, 'LICENSE_FILE', license_file):
-            with patch('httpx.post', return_value=mock_response):
+        with patch.object(lic, "LICENSE_FILE", license_file):
+            with patch("httpx.post", return_value=mock_response):
                 result = activate_license("test-key-123")
 
         assert result is True
@@ -329,7 +341,7 @@ def test_failed_activation(self):
             "error": "Invalid key",
         }
 
-        with patch('httpx.post', return_value=mock_response):
+        with patch("httpx.post", return_value=mock_response):
             result = activate_license("invalid-key")
 
         assert result is False
@@ -338,7 +350,7 @@ def test_network_error(self):
         """Should handle network errors gracefully."""
         import httpx
 
-        with patch('httpx.post', side_effect=httpx.HTTPError("Network error")):
+        with patch("httpx.post", side_effect=httpx.HTTPError("Network error")):
             result = activate_license("test-key")
 
         assert result is False
@@ -351,6 +363,7 @@ class TestShowLicenseStatus:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -358,6 +371,7 @@ def reset_cache(self):
     def test_shows_community_status(self, capsys):
         """Should show community tier status."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         show_license_status()
@@ -369,6 +383,7 @@ def test_shows_community_status(self, capsys):
     def test_shows_pro_status(self, capsys):
         """Should show pro tier status."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(
             tier=FeatureTier.PRO,
             organization="Test Corp",

From bcb92f6d28be9ae0fdf5b65514b32977e780c8a3 Mon Sep 17 00:00:00 2001
From: Kesavaraja M <krkesavaraja67@gmail.com>
Date: Fri, 16 Jan 2026 08:58:04 +0530
Subject: [PATCH 7/7] chore: sync upstream fixes and documentation updates

---
 tests/test_licensing.py | 51 ++++++++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 18 deletions(-)

diff --git a/tests/test_licensing.py b/tests/test_licensing.py
index def55e4a..68f64c21 100644
--- a/tests/test_licensing.py
+++ b/tests/test_licensing.py
@@ -1,26 +1,27 @@
 """Tests for cortex/licensing.py - License management and feature gating."""
 
 import json
-import pytest
-from datetime import datetime, timezone, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from unittest.mock import patch, MagicMock
+from unittest.mock import MagicMock, patch
+
+import pytest
 
 from cortex.licensing import (
+    FEATURE_NAMES,
+    FEATURE_REQUIREMENTS,
+    LICENSE_FILE,
+    FeatureNotAvailableError,
     FeatureTier,
     LicenseInfo,
-    FEATURE_REQUIREMENTS,
-    FEATURE_NAMES,
+    _get_hostname,
+    activate_license,
+    check_feature,
     get_license_info,
     get_license_tier,
-    check_feature,
     require_feature,
-    activate_license,
     show_license_status,
     show_upgrade_prompt,
-    FeatureNotAvailableError,
-    LICENSE_FILE,
-    _get_hostname,
 )
 
 
@@ -143,19 +144,20 @@ class TestGetLicenseInfo:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
 
     def test_returns_license_info(self):
         """Should return LicenseInfo object."""
-        with patch.object(Path, 'exists', return_value=False):
+        with patch.object(Path, "exists", return_value=False):
             info = get_license_info()
             assert isinstance(info, LicenseInfo)
 
     def test_default_community_tier(self):
         """Should default to community tier when no license file."""
-        with patch.object(Path, 'exists', return_value=False):
+        with patch.object(Path, "exists", return_value=False):
             info = get_license_info()
             assert info.tier == FeatureTier.COMMUNITY
 
@@ -174,14 +176,14 @@ def test_reads_license_file(self, tmp_path):
         license_file = tmp_path / "license.key"
         license_file.write_text(json.dumps(license_data))
 
-        with patch.object(lic, 'LICENSE_FILE', license_file):
+        with patch.object(lic, "LICENSE_FILE", license_file):
             info = get_license_info()
             assert info.tier == "pro"
             assert info.organization == "Test Org"
 
     def test_caches_result(self):
         """Should cache license info."""
-        with patch.object(Path, 'exists', return_value=False):
+        with patch.object(Path, "exists", return_value=False):
             info1 = get_license_info()
             info2 = get_license_info()
             assert info1 is info2
@@ -194,6 +196,7 @@ class TestCheckFeature:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -201,6 +204,7 @@ def reset_cache(self):
     def test_community_features_allowed(self):
         """Community tier should access community features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         # Unknown features default to community
@@ -209,6 +213,7 @@ def test_community_features_allowed(self):
     def test_pro_feature_blocked_for_community(self):
         """Community tier should not access pro features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         assert check_feature("cloud_llm", silent=True) is False
@@ -216,6 +221,7 @@ def test_pro_feature_blocked_for_community(self):
     def test_pro_feature_allowed_for_pro(self):
         """Pro tier should access pro features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.PRO)
 
         assert check_feature("cloud_llm", silent=True) is True
@@ -223,6 +229,7 @@ def test_pro_feature_allowed_for_pro(self):
     def test_enterprise_feature_allowed_for_enterprise(self):
         """Enterprise tier should access all features."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.ENTERPRISE)
 
         assert check_feature("sso", silent=True) is True
@@ -231,6 +238,7 @@ def test_enterprise_feature_allowed_for_enterprise(self):
     def test_shows_upgrade_prompt(self, capsys):
         """Should show upgrade prompt when feature blocked."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         check_feature("cloud_llm", silent=False)
@@ -245,6 +253,7 @@ class TestRequireFeatureDecorator:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -252,6 +261,7 @@ def reset_cache(self):
     def test_allows_when_feature_available(self):
         """Should allow function call when feature available."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.PRO)
 
         @require_feature("cloud_llm")
@@ -263,6 +273,7 @@ def test_func():
     def test_raises_when_feature_blocked(self):
         """Should raise FeatureNotAvailableError when feature blocked."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         @require_feature("cloud_llm")
@@ -297,6 +308,7 @@ class TestActivateLicense:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -314,8 +326,8 @@ def test_successful_activation(self, tmp_path):
             "organization": "Test Org",
         }
 
-        with patch.object(lic, 'LICENSE_FILE', license_file):
-            with patch('httpx.post', return_value=mock_response):
+        with patch.object(lic, "LICENSE_FILE", license_file):
+            with patch("httpx.post", return_value=mock_response):
                 result = activate_license("test-key-123")
 
         assert result is True
@@ -329,7 +341,7 @@ def test_failed_activation(self):
             "error": "Invalid key",
         }
 
-        with patch('httpx.post', return_value=mock_response):
+        with patch("httpx.post", return_value=mock_response):
             result = activate_license("invalid-key")
 
         assert result is False
@@ -338,7 +350,7 @@ def test_network_error(self):
         """Should handle network errors gracefully."""
         import httpx
 
-        with patch('httpx.post', side_effect=httpx.HTTPError("Network error")):
+        with patch("httpx.post", side_effect=httpx.HTTPError("Network error")):
             result = activate_license("test-key")
 
         assert result is False
@@ -351,6 +363,7 @@ class TestShowLicenseStatus:
     def reset_cache(self):
         """Reset license cache before each test."""
         import cortex.licensing as lic
+
         lic._cached_license = None
         yield
         lic._cached_license = None
@@ -358,6 +371,7 @@ def reset_cache(self):
     def test_shows_community_status(self, capsys):
         """Should show community tier status."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(tier=FeatureTier.COMMUNITY)
 
         show_license_status()
@@ -369,6 +383,7 @@ def test_shows_community_status(self, capsys):
     def test_shows_pro_status(self, capsys):
         """Should show pro tier status."""
         import cortex.licensing as lic
+
         lic._cached_license = LicenseInfo(
             tier=FeatureTier.PRO,
             organization="Test Corp",