diffai-python 0.2.9__py3-none-any.whl

diffai/__init__.py

@@ -0,0 +1,63 @@
+"""
+diffai - AI/ML specialized diff tool for deep tensor comparison and analysis
+
+This package provides Python bindings for diffai, a powerful command-line tool
+specialized for comparing AI/ML model files, scientific data, and structured data.
+
+Quick start:
+    >>> import diffai
+    >>> result = diffai.diff("model1.safetensors", "model2.safetensors", stats=True)
+    >>> print(result)
+
+Advanced usage:
+    >>> options = diffai.DiffOptions(
+    ...     stats=True,
+    ...     architecture_comparison=True,
+    ...     output_format="json"
+    ... )
+    >>> result = diffai.diff("model1.safetensors", "model2.safetensors", options)
+"""
+
+from .diffai import (
+    # Main API functions
+    diff,
+    diff_string,
+    run_diffai,
+    verify_installation,
+    
+    # Configuration and result classes
+    DiffOptions,
+    DiffResult,
+    OutputFormat,
+    
+    # Exceptions
+    DiffaiError,
+    BinaryNotFoundError,
+    InvalidInputError,
+    
+    # Version info
+    __version__,
+)
+
+# No backward compatibility imports - clean modern API only
+
+__all__ = [
+    # Main API
+    "diff",
+    "diff_string", 
+    "run_diffai",
+    "verify_installation",
+    
+    # Configuration
+    "DiffOptions",
+    "DiffResult",
+    "OutputFormat",
+    
+    # Exceptions
+    "DiffaiError",
+    "BinaryNotFoundError", 
+    "InvalidInputError",
+    
+    # Metadata
+    "__version__",
+]

diffai/diffai.py

@@ -0,0 +1,452 @@
+"""
+Main diffai module providing Python interface to the diffai CLI tool.
+
+This module provides a high-level Python API for the diffai command-line tool,
+with support for type-safe configuration, structured results, and comprehensive
+error handling.
+"""
+
+import json
+import platform
+import subprocess
+import sys
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("diffai-python")
+except importlib.metadata.PackageNotFoundError:
+    # Fallback for development
+    __version__ = "0.2.9"
+
+
+class OutputFormat(Enum):
+    """Supported output formats for diffai results - exact mapping from CLI."""
+    CLI = "cli"        # Default colored CLI output
+    JSON = "json"      # Machine-readable JSON
+    YAML = "yaml"      # Human-readable YAML
+    UNIFIED = "unified"  # Unified diff format
+
+
+@dataclass
+class DiffOptions:
+    """
+    Configuration options for diffai analysis.
+    
+    Provides a type-safe way to configure all diffai analysis options
+    including ML-specific analysis functions and output formatting.
+    
+    Based on actual CLI options from diffai-cli/src/main.rs
+    """
+    
+    # Output and basic configuration
+    output_format: Optional[OutputFormat] = None
+    input_format: Optional[str] = None  # json, yaml, toml, ini, xml, csv, safetensors, pytorch, numpy, npz, matlab
+    recursive: bool = False
+    path: Optional[str] = None  # Filter by specific path
+    ignore_keys_regex: Optional[str] = None  # Ignore keys matching regex
+    epsilon: Optional[float] = None  # Tolerance for float comparisons
+    array_id_key: Optional[str] = None  # Key for identifying array elements
+    
+    # Core analysis options
+    stats: bool = False
+    verbose: bool = False  # NEW: Added verbose mode
+    show_layer_impact: bool = False
+    quantization_analysis: bool = False
+    sort_by_change_magnitude: bool = False
+    
+    # Enhanced ML analysis (Phase 3 implemented)
+    learning_progress: bool = False
+    convergence_analysis: bool = False
+    anomaly_detection: bool = False
+    gradient_analysis: bool = False
+    memory_analysis: bool = False
+    inference_speed_estimate: bool = False
+    regression_test: bool = False
+    alert_on_degradation: bool = False
+    review_friendly: bool = False
+    change_summary: bool = False
+    risk_assessment: bool = False
+    architecture_comparison: bool = False
+    param_efficiency_analysis: bool = False
+    hyperparameter_impact: bool = False
+    learning_rate_analysis: bool = False
+    deployment_readiness: bool = False
+    performance_impact_estimate: bool = False
+    generate_report: bool = False
+    markdown_output: bool = False
+    include_charts: bool = False
+    embedding_analysis: bool = False
+    similarity_matrix: bool = False
+    clustering_change: bool = False
+    attention_analysis: bool = False
+    head_importance: bool = False
+    attention_pattern_diff: bool = False
+    
+    # Phase 2 options
+    hyperparameter_comparison: bool = False
+    learning_curve_analysis: bool = False
+    statistical_significance: bool = False
+    
+    # Additional options
+    extra_args: List[str] = field(default_factory=list)
+    
+    def to_cli_args(self) -> List[str]:
+        """Convert options to CLI arguments based on actual CLI structure."""
+        args = []
+        
+        # Input format
+        if self.input_format:
+            args.extend(["--format", self.input_format])
+        
+        # Output format
+        if self.output_format:
+            args.extend(["--output", self.output_format.value])
+        
+        # String options
+        if self.path:
+            args.extend(["--path", self.path])
+        if self.ignore_keys_regex:
+            args.extend(["--ignore-keys-regex", self.ignore_keys_regex])
+        if self.epsilon is not None:
+            args.extend(["--epsilon", str(self.epsilon)])
+        if self.array_id_key:
+            args.extend(["--array-id-key", self.array_id_key])
+        
+        # Boolean flags - exact mapping from CLI
+        flag_mapping = {
+            "recursive": "--recursive",
+            "stats": "--stats",
+            "verbose": "--verbose",  # NEW: Added verbose mode
+            "show_layer_impact": "--show-layer-impact",
+            "quantization_analysis": "--quantization-analysis",
+            "sort_by_change_magnitude": "--sort-by-change-magnitude",
+            "learning_progress": "--learning-progress",
+            "convergence_analysis": "--convergence-analysis",
+            "anomaly_detection": "--anomaly-detection",
+            "gradient_analysis": "--gradient-analysis",
+            "memory_analysis": "--memory-analysis",
+            "inference_speed_estimate": "--inference-speed-estimate",
+            "regression_test": "--regression-test",
+            "alert_on_degradation": "--alert-on-degradation",
+            "review_friendly": "--review-friendly",
+            "change_summary": "--change-summary",
+            "risk_assessment": "--risk-assessment",
+            "architecture_comparison": "--architecture-comparison",
+            "param_efficiency_analysis": "--param-efficiency-analysis",
+            "hyperparameter_impact": "--hyperparameter-impact",
+            "learning_rate_analysis": "--learning-rate-analysis",
+            "deployment_readiness": "--deployment-readiness",
+            "performance_impact_estimate": "--performance-impact-estimate",
+            "generate_report": "--generate-report",
+            "markdown_output": "--markdown-output",
+            "include_charts": "--include-charts",
+            "embedding_analysis": "--embedding-analysis",
+            "similarity_matrix": "--similarity-matrix",
+            "clustering_change": "--clustering-change",
+            "attention_analysis": "--attention-analysis",
+            "head_importance": "--head-importance",
+            "attention_pattern_diff": "--attention-pattern-diff",
+            "hyperparameter_comparison": "--hyperparameter-comparison",
+            "learning_curve_analysis": "--learning-curve-analysis",
+            "statistical_significance": "--statistical-significance",
+        }
+        
+        for option, flag in flag_mapping.items():
+            if getattr(self, option):
+                args.append(flag)
+        
+        # Extra arguments
+        args.extend(self.extra_args)
+        
+        return args
+
+
+class DiffaiError(Exception):
+    """Base exception for diffai-related errors."""
+    
+    def __init__(self, message: str, exit_code: Optional[int] = None, stderr: Optional[str] = None):
+        super().__init__(message)
+        self.exit_code = exit_code
+        self.stderr = stderr
+
+
+class BinaryNotFoundError(DiffaiError):
+    """Raised when the diffai binary cannot be found."""
+    pass
+
+
+class InvalidInputError(DiffaiError):
+    """Raised when input files or arguments are invalid."""
+    pass
+
+
+class DiffResult:
+    """
+    Structured result from diffai analysis.
+    
+    Provides convenient access to diff results with automatic JSON parsing
+    for structured data and raw text access for other formats.
+    """
+    
+    def __init__(self, raw_output: str, exit_code: int = 0, format_type: str = "diffai"):
+        self.raw_output = raw_output
+        self.exit_code = exit_code
+        self.format_type = format_type
+        self._parsed_data = None
+        
+    @property
+    def data(self) -> Any:
+        """Get parsed data (JSON objects for JSON output, raw string otherwise)."""
+        if self._parsed_data is None:
+            if self.format_type == "json" and self.raw_output.strip():
+                try:
+                    self._parsed_data = json.loads(self.raw_output)
+                except json.JSONDecodeError:
+                    self._parsed_data = self.raw_output
+            else:
+                self._parsed_data = self.raw_output
+        return self._parsed_data
+    
+    @property
+    def is_json(self) -> bool:
+        """True if result is in JSON format."""
+        return self.format_type == "json" and isinstance(self.data, (dict, list))
+    
+    @property
+    def changes(self) -> List[Dict[str, Any]]:
+        """Get list of changes (for JSON output)."""
+        if self.is_json and isinstance(self.data, list):
+            return self.data
+        return []
+    
+    @property
+    def summary(self) -> Dict[str, Any]:
+        """Get summary information (for JSON output)."""
+        if self.is_json and isinstance(self.data, dict):
+            return self.data
+        return {}
+    
+    def __str__(self) -> str:
+        """String representation of the result."""
+        return self.raw_output
+    
+    def __repr__(self) -> str:
+        """Detailed representation of the result."""
+        return f"DiffResult(format={self.format_type}, exit_code={self.exit_code}, length={len(self.raw_output)})"
+
+
+def _get_diffai_binary_path() -> str:
+    """
+    Get the path to the diffai binary.
+    
+    Checks for local installation first, then falls back to system PATH.
+    """
+    # Check for local installation (installed via pip)
+    package_dir = Path(__file__).parent.parent.parent
+    binary_name = "diffai.exe" if platform.system() == "Windows" else "diffai"
+    local_binary_path = package_dir / "bin" / binary_name
+    
+    if local_binary_path.exists():
+        return str(local_binary_path)
+    
+    # Check package-local bin directory
+    package_bin = Path(__file__).parent.parent / "bin" / binary_name
+    if package_bin.exists():
+        return str(package_bin)
+    
+    # Fall back to system PATH
+    return "diffai"
+
+
+def verify_installation() -> Dict[str, Any]:
+    """
+    Verify that diffai is properly installed and accessible.
+    
+    Returns:
+        Dict containing installation status and version information.
+        
+    Raises:
+        BinaryNotFoundError: If diffai binary cannot be found or executed.
+    """
+    try:
+        binary_path = _get_diffai_binary_path()
+        result = subprocess.run(
+            [binary_path, "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10
+        )
+        
+        if result.returncode == 0:
+            version_output = result.stdout.strip()
+            info: Dict[str, str] = {
+                "binary_path": binary_path,
+                "version": version_output,
+                "status": "ok"
+            }
+            return info
+        else:
+            raise BinaryNotFoundError(
+                f"diffai binary found at {binary_path} but failed to execute: {result.stderr}"
+            )
+            
+    except subprocess.TimeoutExpired:
+        raise BinaryNotFoundError("diffai binary execution timed out")
+    except FileNotFoundError:
+        raise BinaryNotFoundError(
+            "diffai binary not found. Please install diffai or ensure it's in your PATH. "
+            "See: https://github.com/kako-jun/diffai/releases"
+        )
+    except Exception as e:
+        raise BinaryNotFoundError(f"Failed to verify diffai installation: {e}")
+
+
+def run_diffai(args: List[str], timeout: Optional[int] = None) -> DiffResult:
+    """
+    Execute diffai with specified arguments.
+    
+    Args:
+        args: Command-line arguments to pass to diffai
+        timeout: Maximum execution time in seconds
+        
+    Returns:
+        DiffResult object containing execution results
+        
+    Raises:
+        DiffaiError: If execution fails
+        BinaryNotFoundError: If diffai binary cannot be found
+    """
+    try:
+        binary_path = _get_diffai_binary_path()
+        cmd = [binary_path] + args
+        
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=timeout
+        )
+        
+        # Determine output format
+        format_type = "json" if "--output" in args and "json" in args else "diffai"
+        
+        if result.returncode == 0:
+            return DiffResult(result.stdout, result.returncode, format_type)
+        else:
+            # Handle common error cases
+            if "No such file" in result.stderr or "not found" in result.stderr:
+                raise InvalidInputError(
+                    f"Input file not found: {result.stderr}",
+                    result.returncode,
+                    result.stderr
+                )
+            else:
+                raise DiffaiError(
+                    f"diffai execution failed: {result.stderr}",
+                    result.returncode,
+                    result.stderr
+                )
+                
+    except subprocess.TimeoutExpired:
+        raise DiffaiError(f"diffai execution timed out after {timeout} seconds")
+    except FileNotFoundError:
+        raise BinaryNotFoundError(
+            "diffai binary not found. Please install diffai or ensure it's in your PATH."
+        )
+
+
+def diff(
+    input1: str,
+    input2: str, 
+    options: Optional[Union[DiffOptions, Dict[str, Any]]] = None,
+    **kwargs
+) -> DiffResult:
+    """
+    Compare two files using diffai.
+    
+    Args:
+        input1: Path to first input file
+        input2: Path to second input file  
+        options: DiffOptions object or dict of options
+        **kwargs: Additional options as keyword arguments
+        
+    Returns:
+        DiffResult object containing comparison results
+        
+    Example:
+        >>> result = diff("model1.safetensors", "model2.safetensors", stats=True)
+        >>> print(result)
+        
+        >>> options = DiffOptions(stats=True, architecture_comparison=True)
+        >>> result = diff("model1.safetensors", "model2.safetensors", options)
+    """
+    # Handle different option formats
+    if options is None:
+        options = DiffOptions(**kwargs)
+    elif isinstance(options, dict):
+        combined_options: Dict[str, Any] = {**options, **kwargs}
+        options = DiffOptions(**combined_options)
+    elif kwargs:
+        # Merge kwargs into existing DiffOptions
+        option_dict = {
+            field.name: getattr(options, field.name) 
+            for field in options.__dataclass_fields__.values()
+        }
+        combined_options = {**option_dict, **kwargs}
+        merged_opts: Dict[str, Union[str, bool, int, float, None]] = combined_options
+        options = DiffOptions(**merged_opts)
+    
+    # Build command arguments
+    args = [input1, input2]
+    args.extend(options.to_cli_args())
+    
+    return run_diffai(args)
+
+
+def diff_string(
+    content1: str, 
+    content2: str, 
+    format_type: Union[str, None] = None,
+    **kwargs
+) -> DiffResult:
+    """
+    Compare two strings using diffai (creates temporary files).
+    
+    Args:
+        content1: First string content
+        content2: Second string content
+        **kwargs: Options passed to diff()
+        
+    Returns:
+        DiffResult object containing comparison results
+        
+    Note:
+        This function creates temporary files for string comparison.
+        Use diff() directly for file-based comparisons.
+    """
+    import tempfile
+    import os
+    
+    # Create temporary files
+    with tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f1, \
+         tempfile.NamedTemporaryFile(mode='w', suffix='.json', delete=False) as f2:
+        
+        f1.write(content1)
+        f2.write(content2)
+        f1_path = f1.name
+        f2_path = f2.name
+    
+    try:
+        return diff(f1_path, f2_path, **kwargs)
+    finally:
+        # Clean up temporary files
+        try:
+            os.unlink(f1_path)
+            os.unlink(f2_path)
+        except OSError:
+            pass  # Ignore cleanup errors

diffai/installer.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""
+Binary installer for diffai Python package.
+
+This module handles downloading and installing platform-specific diffai binaries
+from GitHub releases. It supports automatic platform detection and graceful
+error handling for environments where binary installation fails.
+"""
+
+import argparse
+import hashlib
+import os
+import platform
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import urllib.request
+import zipfile
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+import importlib.metadata
+
+try:
+    PACKAGE_VERSION = importlib.metadata.version("diffai-python")
+except importlib.metadata.PackageNotFoundError:
+    # Fallback for development
+    PACKAGE_VERSION = "0.2.8"
+
+GITHUB_REPO = "kako-jun/diffai"
+RELEASES_URL = f"https://github.com/{GITHUB_REPO}/releases/download/v{PACKAGE_VERSION}"
+
+
+def get_platform_info() -> Dict[str, str]:
+    """
+    Detect current platform and return appropriate binary information.
+    
+    Returns:
+        Dictionary containing platform-specific binary information
+        
+    Raises:
+        ValueError: If platform is not supported
+    """
+    system = platform.system()
+    machine = platform.machine()
+    
+    # Normalize architecture names
+    if machine in ('x86_64', 'AMD64'):
+        arch = 'x86_64'
+    elif machine in ('arm64', 'aarch64'):
+        arch = 'aarch64'
+    else:
+        raise ValueError(f"Unsupported architecture: {machine}")
+    
+    if system == "Windows":
+        return {
+            "platform": "windows",
+            "arch": arch,
+            "extension": "zip",
+            "binary_name": "diffai.exe",
+            "archive_name": f"diffai-windows-{arch}.zip"
+        }
+    elif system == "Darwin":
+        return {
+            "platform": "macos", 
+            "arch": arch,
+            "extension": "tar.gz",
+            "binary_name": "diffai",
+            "archive_name": f"diffai-macos-{arch}.tar.gz"
+        }
+    elif system == "Linux":
+        return {
+            "platform": "linux",
+            "arch": arch, 
+            "extension": "tar.gz",
+            "binary_name": "diffai",
+            "archive_name": f"diffai-linux-{arch}.tar.gz"
+        }
+    else:
+        raise ValueError(f"Unsupported platform: {system}")
+
+
+def download_file(url: str, destination: Path, chunk_size: int = 8192) -> None:
+    """
+    Download a file from URL to destination path.
+    
+    Args:
+        url: URL to download from
+        destination: Local path to save file
+        chunk_size: Size of chunks to download at a time
+        
+    Raises:
+        urllib.error.URLError: If download fails
+    """
+    print(f"Downloading from: {url}")
+    
+    try:
+        with urllib.request.urlopen(url) as response:
+            if response.status != 200:
+                raise urllib.error.URLError(f"HTTP {response.status}: {response.reason}")
+            
+            total_size = response.headers.get('content-length')
+            if total_size:
+                total_size = int(total_size)
+                print(f"File size: {total_size:,} bytes")
+            
+            downloaded = 0
+            with open(destination, 'wb') as f:
+                while True:
+                    chunk = response.read(chunk_size)
+                    if not chunk:
+                        break
+                    f.write(chunk)
+                    downloaded += len(chunk)
+                    
+                    if total_size:
+                        percent = (downloaded / total_size) * 100
+                        print(f"\rProgress: {percent:.1f}% ({downloaded:,}/{total_size:,} bytes)", end='')
+            
+            if total_size:
+                print()  # New line after progress
+                
+    except Exception as e:
+        if destination.exists():
+            destination.unlink()
+        raise urllib.error.URLError(f"Download failed: {e}")
+
+
+def extract_archive(archive_path: Path, extract_to: Path, platform_info: Dict[str, str]) -> Path:
+    """
+    Extract downloaded archive and return path to binary.
+    
+    Args:
+        archive_path: Path to downloaded archive
+        extract_to: Directory to extract to
+        platform_info: Platform information dictionary
+        
+    Returns:
+        Path to extracted binary
+        
+    Raises:
+        Exception: If extraction fails
+    """
+    print(f"Extracting {archive_path} to {extract_to}")
+    
+    try:
+        if platform_info["extension"] == "zip":
+            with zipfile.ZipFile(archive_path, 'r') as zip_ref:
+                zip_ref.extractall(extract_to)
+        else:  # tar.gz
+            with tarfile.open(archive_path, 'r:gz') as tar_ref:
+                tar_ref.extractall(extract_to)
+        
+        # Find the binary in extracted files
+        binary_name = platform_info["binary_name"]
+        
+        # Check common locations
+        possible_paths = [
+            extract_to / binary_name,
+            extract_to / "diffai" / binary_name,
+            extract_to / f"diffai-{platform_info['platform']}-{platform_info['arch']}" / binary_name,
+        ]
+        
+        for path in possible_paths:
+            if path.exists():
+                return path
+        
+        # If not found in expected locations, search recursively
+        for root, dirs, files in os.walk(extract_to):
+            if binary_name in files:
+                return Path(root) / binary_name
+        
+        raise FileNotFoundError(f"Binary '{binary_name}' not found in extracted archive")
+        
+    except Exception as e:
+        raise Exception(f"Failed to extract archive: {e}")
+
+
+def verify_binary(binary_path: Path) -> bool:
+    """
+    Verify that the downloaded binary is functional.
+    
+    Args:
+        binary_path: Path to binary to verify
+        
+    Returns:
+        True if binary is functional, False otherwise
+    """
+    try:
+        # Make executable on Unix systems
+        if platform.system() != "Windows":
+            os.chmod(binary_path, 0o755)
+        
+        # Test binary execution
+        result = subprocess.run(
+            [str(binary_path), "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10
+        )
+        
+        return result.returncode == 0 and "diffai" in result.stdout.lower()
+        
+    except Exception:
+        return False
+
+
+def install_binary(target_dir: Optional[Path] = None, force: bool = False) -> bool:
+    """
+    Download and install diffai binary.
+    
+    Args:
+        target_dir: Directory to install binary (default: package bin directory)
+        force: Whether to overwrite existing binary
+        
+    Returns:
+        True if installation succeeded, False otherwise
+    """
+    try:
+        platform_info = get_platform_info()
+        print(f"Detected platform: {platform_info['platform']} {platform_info['arch']}")
+        
+        # Determine target directory
+        if target_dir is None:
+            # Install to package bin directory
+            package_dir = Path(__file__).parent.parent.parent
+            target_dir = package_dir / "bin"
+        
+        target_dir.mkdir(parents=True, exist_ok=True)
+        binary_path = target_dir / platform_info["binary_name"]
+        
+        # Check if binary already exists
+        if binary_path.exists() and not force:
+            if verify_binary(binary_path):
+                print(f"diffai binary already exists and is functional: {binary_path}")
+                return True
+            else:
+                print(f"Existing binary appears corrupted, replacing: {binary_path}")
+        
+        # Download and install
+        download_url = f"{RELEASES_URL}/{platform_info['archive_name']}"
+        
+        with tempfile.TemporaryDirectory() as temp_dir:
+            temp_path = Path(temp_dir)
+            archive_path = temp_path / platform_info["archive_name"]
+            
+            # Download archive
+            download_file(download_url, archive_path)
+            
+            # Extract archive
+            extracted_binary = extract_archive(archive_path, temp_path, platform_info)
+            
+            # Verify extracted binary
+            if not verify_binary(extracted_binary):
+                raise Exception("Downloaded binary failed verification")
+            
+            # Move to target location
+            shutil.move(str(extracted_binary), str(binary_path))
+            
+            print(f"Successfully installed diffai binary to: {binary_path}")
+            return True
+            
+    except Exception as e:
+        print(f"Failed to install diffai binary: {e}", file=sys.stderr)
+        print(f"Manual installation available at: {RELEASES_URL}", file=sys.stderr)
+        return False
+
+
+def main() -> int:
+    """
+    Main entry point for diffai-download-binary command.
+    
+    Returns:
+        Exit code (0 for success, 1 for failure)
+    """
+    parser = argparse.ArgumentParser(
+        description="Download and install diffai binary",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  diffai-download-binary                    # Install to default location
+  diffai-download-binary --force           # Force reinstall 
+  diffai-download-binary --target ./bin    # Install to specific directory
+  diffai-download-binary --verify          # Verify existing installation
+        """
+    )
+    
+    parser.add_argument(
+        "--target",
+        type=Path,
+        help="Target directory for installation (default: package bin directory)"
+    )
+    
+    parser.add_argument(
+        "--force", 
+        action="store_true",
+        help="Force reinstallation even if binary exists"
+    )
+    
+    parser.add_argument(
+        "--verify",
+        action="store_true", 
+        help="Only verify existing installation"
+    )
+    
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"diffai-installer {PACKAGE_VERSION}"
+    )
+    
+    args = parser.parse_args()
+    
+    if args.verify:
+        # Verify existing installation
+        target_dir = args.target or (Path(__file__).parent.parent.parent / "bin")
+        platform_info = get_platform_info()
+        binary_path = target_dir / platform_info["binary_name"]
+        
+        if binary_path.exists() and verify_binary(binary_path):
+            print(f"✅ diffai binary is properly installed: {binary_path}")
+            return 0
+        else:
+            print(f"❌ diffai binary not found or not functional: {binary_path}")
+            return 1
+    else:
+        # Install binary
+        success = install_binary(args.target, args.force)
+        return 0 if success else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

diffai_python-0.2.9.dist-info/METADATA

@@ -0,0 +1,391 @@
+Metadata-Version: 2.4
+Name: diffai-python
+Version: 0.2.9
+Summary: AI/ML specialized diff tool for deep tensor comparison and analysis
+Project-URL: Homepage, https://github.com/kako-jun/diffai
+Project-URL: Documentation, https://github.com/kako-jun/diffai/blob/main/docs/
+Project-URL: Repository, https://github.com/kako-jun/diffai.git
+Project-URL: Issues, https://github.com/kako-jun/diffai/issues
+Project-URL: Changelog, https://github.com/kako-jun/diffai/blob/main/CHANGELOG.md
+Author: kako-jun
+License-Expression: MIT
+Keywords: ai,artificial-intelligence,diff,diffai,machine-learning,matlab,ml,model-comparison,numpy,pytorch,safetensors,tensor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: General
+Classifier: Topic :: Utilities
+Requires-Python: >=3.8
+Provides-Extra: dev
+Requires-Dist: black>=22.0; extra == 'dev'
+Requires-Dist: flake8>=5.0; extra == 'dev'
+Requires-Dist: mypy>=0.991; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: types-requests>=2.28; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# diffai - AI/ML Specialized Diff Tool (Python Package)
+
+[![PyPI version](https://badge.fury.io/py/diffai-python.svg)](https://badge.fury.io/py/diffai-python)
+[![Downloads](https://img.shields.io/pypi/dm/diffai-python.svg)](https://pypi.org/project/diffai-python/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/diffai-python.svg)](https://pypi.org/project/diffai-python/)
+
+AI/ML specialized data diff tool for deep tensor comparison and analysis. This Python package provides a convenient and type-safe interface to diffai through Python.
+
+## 🚀 Quick Start
+
+### Installation
+
+```bash
+# Install via pip
+pip install diffai-python
+
+# Development installation
+pip install diffai-python[dev]
+```
+
+### Basic Usage
+
+```python
+import diffai
+
+# Simple model comparison
+result = diffai.diff("model_v1.safetensors", "model_v2.safetensors", stats=True)
+print(result)
+
+# Advanced ML analysis with type-safe configuration
+options = diffai.DiffOptions(
+    stats=True,
+    architecture_comparison=True,
+    memory_analysis=True,
+    output_format=diffai.OutputFormat.JSON
+)
+
+result = diffai.diff("baseline.safetensors", "improved.safetensors", options)
+if result.is_json:
+    for change in result.changes:
+        print(f"Changed: {change}")
+```
+
+### Command Line Usage
+
+```bash
+# The package also installs the diffai binary
+diffai model1.safetensors model2.safetensors --stats
+
+# Download binary manually if needed
+diffai-download-binary
+```
+
+## 📦 Supported File Formats
+
+### AI/ML Formats (Specialized Analysis)
+- **Safetensors** (.safetensors) - PyTorch model format with ML analysis
+- **PyTorch** (.pt, .pth) - Native PyTorch models with tensor statistics
+- **NumPy** (.npy, .npz) - Scientific computing arrays with statistical analysis
+- **MATLAB** (.mat) - Engineering/scientific data with numerical analysis
+
+### Structured Data Formats (Universal)
+- **JSON** (.json) - API configurations, model metadata
+- **YAML** (.yaml, .yml) - Configuration files, CI/CD pipelines
+- **TOML** (.toml) - Rust configs, Python pyproject.toml
+- **XML** (.xml) - Legacy configurations, model definitions
+- **CSV** (.csv) - Datasets, experiment results
+- **INI** (.ini) - Legacy configuration files
+
+## 🔬 35 ML Analysis Functions
+
+### Core Analysis Functions
+```python
+# Statistical analysis
+result = diffai.diff("model1.safetensors", "model2.safetensors", stats=True)
+
+# Quantization analysis
+result = diffai.diff("fp32.safetensors", "quantized.safetensors", 
+                    quantization_analysis=True)
+
+# Change magnitude sorting
+result = diffai.diff("model1.safetensors", "model2.safetensors", 
+                    sort_by_change_magnitude=True, stats=True)
+```
+
+### Phase 3 Advanced Analysis (v0.2.7+)
+```python
+# Architecture comparison
+result = diffai.diff("model1.safetensors", "model2.safetensors", 
+                    architecture_comparison=True)
+
+# Memory analysis for deployment
+result = diffai.diff("model1.safetensors", "model2.safetensors", 
+                    memory_analysis=True)
+
+# Anomaly detection for debugging
+result = diffai.diff("stable.safetensors", "problematic.safetensors", 
+                    anomaly_detection=True)
+
+# Comprehensive analysis
+options = diffai.DiffOptions(
+    stats=True,
+    architecture_comparison=True,
+    memory_analysis=True,
+    anomaly_detection=True,
+    convergence_analysis=True,
+    gradient_analysis=True,
+    similarity_matrix=True,
+    change_summary=True
+)
+result = diffai.diff("baseline.safetensors", "improved.safetensors", options)
+```
+
+## 💡 Python API Examples
+
+### Type-Safe Configuration
+```python
+from diffai import DiffOptions, OutputFormat
+
+# Create type-safe configuration
+options = DiffOptions(
+    stats=True,
+    architecture_comparison=True,
+    memory_analysis=True,
+    output_format=OutputFormat.JSON
+)
+
+# Compare models
+result = diffai.diff("model1.safetensors", "model2.safetensors", options)
+
+# Access structured results
+if result.is_json:
+    print(f"Found {len(result.changes)} changes")
+    for change in result.changes:
+        print(f"  {change.get('path')}: {change.get('type')}")
+```
+
+### Scientific Data Analysis
+```python
+# NumPy array comparison
+result = diffai.diff("experiment_v1.npy", "experiment_v2.npy", stats=True)
+print(f"Statistical changes: {result}")
+
+# MATLAB data comparison
+result = diffai.diff("simulation_v1.mat", "simulation_v2.mat", 
+                    stats=True, sort_by_change_magnitude=True)
+```
+
+### JSON Output for Automation
+```python
+# Get JSON results for MLOps integration
+result = diffai.diff("model1.safetensors", "model2.safetensors", 
+                    stats=True, output_format=diffai.OutputFormat.JSON)
+
+if result.is_json:
+    # Process structured data
+    changes = result.changes
+    summary = result.summary
+    
+    # Integration with MLflow, Weights & Biases, etc.
+    log_model_comparison(changes, summary)
+```
+
+### Error Handling
+```python
+try:
+    result = diffai.diff("model1.safetensors", "model2.safetensors", stats=True)
+    print(result)
+except diffai.BinaryNotFoundError:
+    print("diffai binary not found. Please install: pip install diffai-python")
+except diffai.InvalidInputError as e:
+    print(f"Invalid input: {e}")
+except diffai.DiffaiError as e:
+    print(f"diffai error: {e}")
+```
+
+### String Comparison (Temporary Files)
+```python
+# Compare JSON strings directly
+json1 = '{"model": "gpt-2", "layers": 12}'
+json2 = '{"model": "gpt-2", "layers": 24}'
+
+result = diffai.diff_string(json1, json2, output_format=diffai.OutputFormat.JSON)
+print(result)
+```
+
+## 🔧 Advanced Usage
+
+### Installation Verification
+```python
+# Check if diffai is properly installed
+try:
+    info = diffai.verify_installation()
+    print(f"diffai version: {info['version']}")
+    print(f"Binary path: {info['binary_path']}")
+except diffai.BinaryNotFoundError as e:
+    print(f"Installation issue: {e}")
+```
+
+### Manual Binary Management
+```python
+# Download binary programmatically
+from diffai.installer import install_binary
+
+success = install_binary(force=True)  # Force reinstall
+if success:
+    print("Binary installed successfully")
+```
+
+### Low-Level API Access
+```python
+# Direct command execution
+result = diffai.run_diffai([
+    "model1.safetensors", 
+    "model2.safetensors", 
+    "--stats", 
+    "--architecture-comparison",
+    "--output", "json"
+])
+
+print(f"Exit code: {result.exit_code}")
+print(f"Output: {result.raw_output}")
+```
+
+## 🔗 Integration Examples
+
+### MLflow Integration
+```python
+import mlflow
+import diffai
+
+def log_model_comparison(model1_path, model2_path, run_id=None):
+    with mlflow.start_run(run_id=run_id):
+        # Compare models with comprehensive analysis
+        result = diffai.diff(
+            model1_path, model2_path,
+            stats=True,
+            architecture_comparison=True,
+            memory_analysis=True,
+            output_format=diffai.OutputFormat.JSON
+        )
+        
+        if result.is_json:
+            # Log structured comparison data
+            mlflow.log_dict(result.data, "model_comparison.json")
+            
+            # Log metrics
+            if result.changes:
+                mlflow.log_metric("total_changes", len(result.changes))
+                mlflow.log_metric("significant_changes", 
+                                sum(1 for c in result.changes 
+                                    if c.get('magnitude', 0) > 0.1))
+
+# Usage
+log_model_comparison("baseline.safetensors", "candidate.safetensors")
+```
+
+### Weights & Biases Integration
+```python
+import wandb
+import diffai
+
+def wandb_log_model_diff(model1, model2, **kwargs):
+    result = diffai.diff(model1, model2, 
+                        stats=True, 
+                        output_format=diffai.OutputFormat.JSON,
+                        **kwargs)
+    
+    if result.is_json and result.changes:
+        # Log to wandb
+        wandb.log({
+            "model_comparison": wandb.Table(
+                columns=["parameter", "change_type", "magnitude"],
+                data=[[c.get("path"), c.get("type"), c.get("magnitude")] 
+                      for c in result.changes[:100]]  # Limit rows
+            )
+        })
+
+# Initialize wandb run
+wandb.init(project="model-comparison")
+wandb_log_model_diff("model_v1.safetensors", "model_v2.safetensors")
+```
+
+### Flask API Endpoint
+```python
+from flask import Flask, request, jsonify
+import diffai
+
+app = Flask(__name__)
+
+@app.route('/compare', methods=['POST'])
+def compare_models():
+    try:
+        files = request.files
+        model1 = files['model1']
+        model2 = files['model2']
+        
+        # Save temporary files
+        model1.save('/tmp/model1.safetensors')
+        model2.save('/tmp/model2.safetensors')
+        
+        # Compare models
+        result = diffai.diff('/tmp/model1.safetensors', '/tmp/model2.safetensors',
+                           stats=True, 
+                           architecture_comparison=True,
+                           output_format=diffai.OutputFormat.JSON)
+        
+        return jsonify({
+            "status": "success",
+            "comparison": result.data if result.is_json else result.raw_output
+        })
+        
+    except diffai.DiffaiError as e:
+        return jsonify({"status": "error", "message": str(e)}), 400
+
+if __name__ == '__main__':
+    app.run(debug=True)
+```
+
+## 🏗️ Platform Support
+
+This package automatically downloads platform-specific binaries:
+
+- **Linux** (x86_64, ARM64)
+- **macOS** (Intel x86_64, Apple Silicon ARM64)
+- **Windows** (x86_64)
+
+The binary is downloaded during installation and cached. If download fails, the package falls back to system PATH.
+
+## 🔗 Related Projects
+
+- **[diffx-python](https://pypi.org/project/diffx-python/)** - General-purpose structured data diff tool
+- **[diffai (npm)](https://www.npmjs.com/package/diffai)** - Node.js package for diffai
+- **[diffai (GitHub)](https://github.com/diffai-team/diffai)** - Main repository
+
+## 📚 Documentation
+
+- [CLI Reference](https://github.com/diffai-team/diffai/blob/main/docs/reference/cli-reference.md)
+- [ML Analysis Guide](https://github.com/diffai-team/diffai/blob/main/docs/reference/ml-analysis.md)
+- [User Guide](https://github.com/diffai-team/diffai/blob/main/docs/user-guide/)
+- [API Documentation](https://github.com/diffai-team/diffai/blob/main/docs/reference/api-reference.md)
+
+## 📄 License
+
+MIT License - see [LICENSE](https://github.com/diffai-team/diffai/blob/main/LICENSE) file for details.
+
+## 🤝 Contributing
+
+Contributions welcome! Please see [CONTRIBUTING.md](https://github.com/diffai-team/diffai/blob/main/CONTRIBUTING.md) for guidelines.
+
+---
+
+**diffai** - Making AI/ML data differences visible, measurable, and actionable through Python. 🐍🚀

diffai_python-0.2.9.dist-info/RECORD

@@ -0,0 +1,7 @@
+diffai/__init__.py,sha256=iKtiy7DNC0yV3LNp3iImdGQeEtxIF-81Rh58naWj1iA,1360
+diffai/diffai.py,sha256=C1y4Jly9L2FwqpWVVII4eoTIIy7Dwn9juf0bhI-k3x0,15586
+diffai/installer.py,sha256=l3cXX516rvx-m9jbk1THZL5SauYMlPsziD9_-rm3Juo,10662
+diffai_python-0.2.9.dist-info/METADATA,sha256=oI2ielcDpD67qnzSjz1EqvWN3qNjyEqSEnY7rzf70Ng,12452
+diffai_python-0.2.9.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+diffai_python-0.2.9.dist-info/entry_points.txt,sha256=iL4_2-iwaeQSnqkD5jh6NqsPXPiyU7R4zqg23-J1Xbk,65
+diffai_python-0.2.9.dist-info/RECORD,,

diffai_python-0.2.9.dist-info/WHEEL

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

diffai_python-0.2.9.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+diffai-download-binary = diffai.installer:main