src/tools/forensic_tools.py

"""
Forensic tools for agent use.
"""

from typing import List

from langchain_core.tools import Tool

from .forensic import (
    analyze_frequency_domain,
    analyze_jpeg_compression,
    detect_jpeg_quantization,
    extract_residuals,
    perform_ela,
    perform_trufor,
    run_code_interpreter,
    perform_cfa_detection,
)


def create_forensic_tools() -> List[Tool]:
    """
    Create LangChain tools for forensic operations.

    Returns:
        List of Tool instances
    """

    tools = [
        Tool(
            name="analyze_jpeg_compression",
            func=analyze_jpeg_compression,
            description=(
                "Analyze JPEG compression artifacts and quantization tables. "
                "Use this to detect compression history and quality inconsistencies. "
                "Input format: 'image_path'. Example: 'path/to/image.jpg'"
            ),
        ),
        Tool(
            name="analyze_frequency_domain",
            func=analyze_frequency_domain,
            description=(
                "Analyze DCT/FFT frequency domain features. "
                "Use this to detect frequency domain anomalies that may indicate manipulation. "
                "Input format: 'image_path'. Example: 'path/to/image.jpg'"
            ),
        ),
        Tool(
            name="extract_residuals",
            func=extract_residuals,
            description=(
                "Extract denoiser residual statistics using DRUNet (deep learning denoiser). "
                "This tool applies a state-of-the-art neural network denoiser and analyzes the residual patterns. "
                "Returns comprehensive statistics: residual_mean, residual_std, residual_skew, residual_kurtosis, "
                "residual_energy, residual_energy_mean, residual_energy_std, residual_energy_p95. "
                "Use this to detect statistical anomalies in image residuals that may indicate manipulation, "
                "AI generation, or compression artifacts. Higher energy values or unusual distributions may indicate tampering. "
                "Input format: 'image_path'. Example: 'path/to/image.jpg'"
            ),
        ),
        Tool(
            name="detect_jpeg_quantization",
            func=detect_jpeg_quantization,
            description=(
                "Extract JPEG quantization tables, estimate quality, and flag double-compression periodicity. "
                "Input format: 'image_path'. Example: 'path/to/image.jpg'"
            ),
        ),
        Tool(
            name="perform_ela",
            func=perform_ela,
            description=(
                "Run Error Level Analysis (recompress at fixed JPEG quality, compute error map). "
                "Outputs ela_map (base64 PNG), ela_mean, ela_std, ela_anomaly_score. "
                "Input: image path or JSON with {path, quality, max_size, return_map}."
            ),
        ),
        Tool(
            name="perform_trufor",
            func=perform_trufor,
            description=(
                "Run TruFor AI-driven forgery detection and localization. "
                "TruFor combines RGB features with Noiseprint++ using transformer fusion. "
                "Outputs manipulation_probability, detection_score, and localization_map (base64 PNG). "
                "Input: image path or JSON with {path, gpu, return_map}. "
                "gpu: -1 for CPU, 0+ for GPU device number."
            ),
        ),
        Tool(
            name="execute_python_code",
            func=run_code_interpreter,
            description=(
                "Execute Python code dynamically for custom image analysis. "
                "This tool allows you to write Python code to analyze images, zoom in on regions, "
                "crop areas, compute statistics, create visualizations, etc. "
                "Available variables: 'image' (PIL Image), 'image_array' (numpy array), 'image_path' (str), "
                "'np' (numpy), 'Image' (PIL), 'Path' (pathlib.Path), 'base64', 'json'. "
                "Input format: JSON string with 'code' and optionally 'image_path'. "
                "Example: '{\"code\": \"print(f'Image size: {image.size}')\", \"image_path\": \"path/to/image.jpg\"}' "
                "Or simple string: just the Python code (will use current image_path from context). "
                "You can zoom in by cropping: 'crop = image.crop((x1, y1, x2, y2)); print(crop.size)' "
                "Or analyze regions: 'region = image_array[y1:y2, x1:x2]; print(f\"Mean: {np.mean(region)}\")'"
            ),
        ),
        Tool(
            name="perform_cfa_detection",
            func=perform_cfa_detection,
            description=(
                "CFA (Color Filter Array) consistency analyzer for SPLICE DETECTION. "
                "Analyzes demosaicing pattern uniformity across image windows to find "
                "regions with inconsistent CFA artifacts (potential splices or mixed sources). "
                "NOTE: This tool is for LOCALIZATION, not whole-image authenticity. "
                "Use TruFor for AI-generated image detection. "
                "Input JSON: {\"mode\":\"analyze\",\"image_path\":\"...\","
                "\"window\":256,\"pattern\":\"RGGB\",\"channel\":\"G\",\"top_k\":5}. "
                "Output: cfa_consistency_score (0-1), distribution analysis, outlier windows. "
                "Low consistency or outlier windows may indicate spliced regions."
            ),
        ),
    ]

    return tools