{"id":49541179,"url":"https://github.com/y0sif/rough_hook","last_synced_at":"2026-05-02T15:07:23.272Z","repository":{"id":301961945,"uuid":"864185784","full_name":"y0sif/rough_hook","owner":"y0sif","description":"Research project comparing Kolmogorov-Arnold Networks vs MLPs across chess engines, computer vision, and anomaly detection using Rust.","archived":false,"fork":false,"pushed_at":"2026-01-01T14:49:14.000Z","size":195981,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-06T18:03:35.275Z","etag":null,"topics":["anomaly-detection","chess-engine","computer-vision","kan","machine-learning","mlp","python","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/y0sif.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-09-27T16:49:26.000Z","updated_at":"2026-01-01T14:49:18.000Z","dependencies_parsed_at":"2025-06-29T21:28:45.267Z","dependency_job_id":null,"html_url":"https://github.com/y0sif/rough_hook","commit_stats":null,"previous_names":["y0sif/rough_hook"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/y0sif/rough_hook","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0sif%2Frough_hook","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0sif%2Frough_hook/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0sif%2Frough_hook/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0sif%2Frough_hook/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/y0sif","download_url":"https://codeload.github.com/y0sif/rough_hook/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/y0sif%2Frough_hook/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32538325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T12:25:33.646Z","status":"ssl_error","status_checked_at":"2026-05-02T12:24:51.733Z","response_time":132,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["anomaly-detection","chess-engine","computer-vision","kan","machine-learning","mlp","python","rust"],"created_at":"2026-05-02T15:07:22.627Z","updated_at":"2026-05-02T15:07:23.263Z","avatar_url":"https://github.com/y0sif.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rough Hook\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"assets/RH.png\" width=\"200px\" alt=\"Rough Hook Logo\"\u003e\n  \n  **A Comprehensive Research Framework for Evaluating Kolmogorov-Arnold Networks (KANs) in Chess-Related Applications**\n\u003c/div\u003e\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Research Objectives](#research-objectives)\n- [Project Architecture](#project-architecture)\n- [Installation](#installation)\n  - [System Requirements](#system-requirements)\n  - [Dependencies Installation](#dependencies-installation)\n  - [Project Setup](#project-setup)\n- [Project Components](#project-components)\n  - [Rusty Brain - Chess Engine](#rusty-brain---chess-engine)\n  - [Hook Lens - Computer Vision](#hook-lens---computer-vision)\n  - [Rough Guard - Behavioral Analysis](#rough-guard---behavioral-analysis)\n- [Databases](#databases)\n- [Scripts](#scripts)\n- [Usage Examples](#usage-examples)\n- [Research Results](#research-results)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Overview\n\n**Rough Hook** is a comprehensive research project that empirically evaluates Kolmogorov-Arnold Networks (KANs) across three distinct domains: chess engine evaluation, computer vision classification, and behavioral anomaly detection. This project provides rigorous real-world performance assessment of KANs as a promising alternative to traditional Multi-Layer Perceptrons (MLPs).\n\n## Research Objectives\n\nThis research addresses the critical need for empirical validation of KANs across diverse applications by implementing three modular systems:\n\n1. **Chess Engine Evaluation**: Comparing HCE (Hand-Crafted Evaluation), NNUE, and KAN architectures\n2. **Computer Vision Classification**: Evaluating CNN+MLP vs CNN+KAN for chess piece recognition  \n3. **Behavioral Anomaly Detection**: Assessing MLP vs KAN for chess cheating detection\n\n### Key Research Questions\n- Can KANs replace traditional evaluation functions in chess engines?\n- Do KANs offer advantages in computer vision tasks when computational overhead is justified?\n- How do KANs perform in behavioral pattern recognition compared to MLPs?\n\n## Project Architecture\n\n```\nrough_hook/\n├── rusty_brain/          # Chess engine with switchable evaluation functions\n├── hook_lens/            # Computer vision pipeline for chess piece classification  \n├── rough_guard/          # Behavioral anomaly detection system\n├── cutechess/            # Modified cutechess GUI with Hook Lens \u0026 Rough Guard integration\n├── databases/            # Training and evaluation datasets (see setup instructions)\n├── scripts/              # Data preprocessing and augmentation scripts\n├── nnue_models/          # Pre-trained NNUE neural network models\n└── assets/               # Project assets and documentation\n```\n\n## Installation\n\n### System Requirements\n\n- **Operating System**: Linux (Ubuntu 20.04+ recommended)\n- **Rust**: Latest stable version\n- **Python**: 3.8+\n- **CUDA**: 12.0+ (for GPU acceleration)\n- **Memory**: 16GB+ RAM recommended\n- **Storage**: 50GB+ free space (for datasets)\n\n### Dependencies Installation\n\n#### 1. Install Rust\n```bash\ncurl https://sh.rustup.rs -sSf | sh\nsource $HOME/.cargo/env\n```\n\n#### 2. Install System Dependencies\n```bash\n# Essential build tools\nsudo apt update\nsudo apt install git build-essential libssl-dev pkg-config\n\n# Python and virtual environment\nsudo apt install python3-pip python3-venv\n\n# Mathematical libraries for KAN operations\nsudo apt install gfortran\nsudo apt-get install libatlas-base-dev libblas-dev liblapack-dev\n\n# Computer vision dependencies\nsudo apt install libopencv-dev clang libclang-dev\n\n# Qt dependencies for cutechess GUI\nsudo apt install qtbase5-dev qttools5-dev-tools\n```\n\n#### 3. Install NVIDIA CUDA Toolkit (for GPU acceleration)\n```bash\n# Install NVIDIA toolkit (easier method)\nsudo apt install nvidia-cuda-toolkit\n```\n\n### Project Setup\n\n#### 1. Clone the Repository\n```bash\ngit clone https://github.com/y0sif/rough_hook.git\ncd rough_hook\n```\n\n#### 2. Build the Project\n```bash\n# Build all Rust components\ncargo build --release\n\n# Or build individual Rust components\ncargo build -p rusty_brain --release\ncargo build -p hook_lens --release  \ncargo build -p rough_guard --release\n\n# Build cutechess (C++/Qt application)\ncd cutechess/build\ncmake ..\nmake -j$(nproc)\ncd ../..\n```\n\n#### 3. Verify Installation\n```bash\n# Test the chess engine (includes PERFT tests for move generation validation)\ncargo test -p rusty_brain --release\n\n# Run computer vision system\ncargo run -p hook_lens --release\n\n# Run behavioral analysis system\ncargo run -p rough_guard --release\n\n# Test cutechess GUI (should open the chess interface)\ncd cutechess/build\n./cutechess\ncd ../..\n```\n\n## Project Components\n\n### Cutechess Integration\n\nThe project includes a modified version of cutechess with integrated Hook Lens and Rough Guard features.\n\n**Running cutechess with integrated features:**\n```bash\n# Navigate to the cutechess build directory and run the GUI\ncd cutechess/build\n./cutechess\n```\n\n**Accessing integrated features:**\n- Hook Lens integration: Available in the **Tools** menu\n- Rough Guard integration: Available in the **Tools** menu\n\n**Rebuilding cutechess after modifications:**\nIf you make any changes to the cutechess source code, you'll need to rebuild the project:\n\n```bash\n# Clean the build directory\ncd cutechess\nrm -rf build/*\n\n# Regenerate CMake configuration\ncd build\ncmake ..\n\n# Build the project\nmake -j$(nproc)\n```\n\n### Rusty Brain - Chess Engine\n\nA complete UCI-compliant chess engine.\n\n**Features:**\n- Bitboard representation with magic bitboards for sliding pieces\n- Alpha-beta search with iterative deepening\n- Transposition tables for search optimization  \n- Evaluation functions: NNUE\n- UCI protocol support for chess GUI integration\n\n**NNUE Training:**\nNNUE models are trained using the Bullet ML framework: https://github.com/jw1912/bullet\nNote: Unlike Hook Lens and Rough Guard, NNUE training does not use the Burn framework.\n\n**Running the Engine:**\n```bash\n# Start UCI mode\ncargo run -p rusty_brain --release\n\n# Run PERFT tests for move generation validation\ncargo test -p rusty_brain --release\n```\n\n**Key Files:**\n- `src/board.rs` - Chess board representation\n- `src/alphabeta.rs` - Search algorithm implementation\n- `src/evaluation.rs` - Hand-crafted evaluation function\n- `src/nnue.rs` - NNUE integration\n- `src/uci.rs` - UCI protocol implementation\n\n### Hook Lens - Computer Vision\n\nComputer vision pipeline for analyzing chess board images and extracting positions.\n\n**Features:**\n- Automated chess board detection and square extraction\n- CNN+MLP vs CNN+KAN architecture comparison\n- Chess piece classification across 13 classes (6 white, 6 black, empty)\n- FEN string generation from board images\n- Real-time inference capabilities\n\n**Training Models:**\n```bash\n# Training and testing configurations need to be adjusted in the source code\n# Use cargo run to perform training or testing for specific models\ncargo run -p hook_lens --release\n```\n\n**Using for Inference:**\n```bash\n# Training and testing configurations need to be adjusted in the source code\n# Use cargo run for model inference and evaluation\ncargo run -p hook_lens --release\n```\n\n**Key Files:**\n- `src/data_and_model/model.rs` - CNN and KAN model architectures\n- `src/data_and_model/training.rs` - Training pipeline\n- `src/input_data_handling/board_square_extracting.rs` - Image preprocessing\n- `src/input_data_handling/fen_string_generation.rs` - FEN generation\n\n### Rough Guard - Behavioral Analysis\n\nBehavioral anomaly detection system for identifying chess cheating patterns.\n\n**Features:**\n- MLP vs KAN classifier comparison for cheat detection\n- Feature extraction from chess game behavioral data\n- Support for multiple behavioral metrics (time patterns, move accuracy, etc.)\n- Class imbalance handling with weighted loss functions\n\n**Training Models:**\n```bash\n# Training and testing configurations need to be adjusted in the source code\n# Use cargo run to perform training or testing for specific models\ncargo run -p rough_guard --release\n```\n\n**Key Files:**\n- `src/model.rs` - MLP and KAN model definitions\n- `src/training.rs` - Training pipeline with class balancing\n- `src/data.rs` - Data loading and preprocessing\n- `src/inference.rs` - Model inference and evaluation\n\n## Databases\n\nThe project requires several large datasets that are stored externally due to size constraints:\n\n**Download Required Datasets:**\n```bash\n# Create databases directory if it doesn't exist\nmkdir -p databases\n\n# Download from provided Google Drive link\n# [Add your Google Drive link here]\n# Extract to databases/ folder\n```\n\n## Scripts\n\nThe `scripts/` directory contains data preprocessing and augmentation utilities for the project components:\n\n**Hook Lens Scripts (Python):**\n- `data_augmentation_script.py` - Image data augmentation for training\n- `image_resize_script.py` - Batch image resizing utilities\n- `image_splitting_script.py` - Dataset splitting functionality\n\n**Rough Guard Scripts (Python):**\n- `1. PGN Filtering/` - Chess game filtering and preprocessing\n- `2. Feature Extraction \u0026 DB Creation/` - Feature extraction from chess games\n- `3. Database Labeling/` - Automated labeling for training data\n- `4. Separate White \u0026 Black/` - Game data separation by player color\n- `5. Compute Euclidean Distance/` - Distance computation for behavioral analysis\n\n## Usage Examples\n\n### Example 1: Using cutechess with integrated features\n```bash\n# Start cutechess GUI\ncd cutechess/build\n./cutechess\n\n# In the GUI:\n# 1. Go to Tools menu\n# 2. Select \"Hook Lens\" for computer vision features\n# 3. Select \"Rough Guard\" for behavioral analysis features\n```\n\n### Example 2: Chess Engine Analysis\n```bash\n# Start the engine in UCI mode\ncargo run -p rusty_brain --release\n\n# In UCI interface:\nuci\nisready\nposition startpos moves e2e4 e7e5\ngo depth 10\n```\n\n### Example 3: Analyze Chess Board Image\n```bash\n# Configure analysis parameters in source code, then run\ncargo run -p hook_lens --release\n```\n\n### Example 4: Behavioral Analysis\n```bash\n# Configure analysis parameters in source code, then run\ncargo run -p rough_guard --release\n```\n\n## Research Results\n\n**Key Findings:**\n\n### Chess Engine Evaluation\n- **NNUE Performance**: Successfully achieved 2400-2600 Elo rating\n- **KAN Integration**: Faced technical barriers due to CUDA optimization requirements\n- **Conclusion**: Current KAN frameworks lack optimization infrastructure for real-time chess applications\n\n### Computer Vision Classification  \n- **KAN Advantage**: 1.81% accuracy improvement (97.86% vs 96.05%) over CNN+MLP\n- **Computational Cost**: 14.3% increase in inference time (32.93ms vs 28.82ms)  \n- **Optimization**: Hyperparameter tuning more effective than scaling node parameters\n- **Conclusion**: KANs show promise when accuracy gains justify computational overhead\n\n### Behavioral Anomaly Detection\n- **Challenge**: Both KAN and MLP achieved only random-level performance\n- **Insight**: Revealed fundamental feature representation limitations rather than architectural deficiencies\n- **Conclusion**: Success depends more on feature quality than architecture choice\n\n## Contributing\n\n- [Placeholder: contributing to be added]\n\n## License\n\n- [Placeholder: license to be added]\n---\n\n**Note**: This is an active research project. Results and implementations may be updated as research progresses.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy0sif%2Frough_hook","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fy0sif%2Frough_hook","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fy0sif%2Frough_hook/lists"}