Spaces:

grasant
/

canrun

Sleeping

App Files Files Community

canrun / README.md

grasant

Upload 24 files

d86b25e verified 7 months ago

preview code

raw

history blame contribute delete

16.7 kB

A newer version of the Gradio SDK is available: 6.5.1

Upgrade

metadata

title: >-
  CanRun – tells you if your PC can run any game with an advanced **S-A-B-C-D-F
  tier system
emoji: 🎮
colorFrom: red
colorTo: gray
sdk: gradio
app_file: app.py
pinned: false
license: apache-2.0
tags:
  - mcp-server
  - hardvare-check
  - gradio
  - python
  - mathematics
  - llm-tools

CanRun - System Spec Game Compatibility Checker

🚀 Overview

CanRun is an RTX/GTX-exclusive G-Assist plugin that instantly tells you if your PC can run any game with an advanced S-A-B-C-D-F tier system.and enhanced Steam integration.

✨ Key Features

🎯 RTX/GTX Optimized: Exclusively designed for RTX/GTX systems with G-Assist integration
🎮 CANRUN! Indicator: Instant visual feedback when your system meets game requirements
⭐ S-A-B-C-D-F Tier System: Advanced performance classification with weighted scoring (GPU 60%, CPU 25%, RAM 15%)
🧠 AI-Powered Analysis: Leverages G-Assist's embedded 8B Llama model for intelligent insights
🔒 Privacy-by-Design: All processing happens locally on your RTX GPU—no data leaves your system
🎯 Steam-First Data: Prioritizes Steam API for most up-to-date game requirements
🎯 Intelligent Game Matching: Advanced fuzzy matching handles game name variations
📊 Smart Performance Prediction: Comprehensive hardware hierarchies with RTX 30/20 series support
💡 Intelligent Recommendations: AI-generated optimization tips, DLSS strategies, upgrade suggestions
🏃 Zero Setup: Drop-in plugin with automatic RTX/GTX validation
🤖 MCP Server: Official Model Context Protocol (MCP) server for G-Assist integration

Live Demo

HF Space Demo

# Test the transformation - RTX 3080 + Intel i7-12700K system
uv run python plugin.py --function check_compatibility --game "Diablo 4"

# Result: CanRun Analysis: Diablo 4 - Tier A - EXCELLENT
# Score: 92/100 (Previously: 49/100)
# Steam API: ✅ Working (ID: 2344520)
# Performance Tier: A (Previously: F)

🏁 Quick Start (For Judges)

1-Minute Setup & Verification:

# 1. Clone and enter directory
git clone https://github.com/leksval/canrun
cd canrun

# 2. Install dependencies with uv (recommended)
uv sync

# 3. Test the official G-Assist protocol
python test/test_official_g_assist_protocol.py
# Expected: All tests PASSING with official protocol

# 4. Test enhanced G-Assist plugin
uv run python plugin.py --function check_compatibility --game "Diablo 4" --show-steam
# Expected: Enhanced G-Assist response with Steam Compare UI

# 5. Test natural language auto-detection
uv run python plugin.py --function auto_detect --input "Can I run Elden Ring?"
# Expected: Automatic routing to compatibility check

Enhanced G-Assist Voice Commands (v5.1 Ready):

"Can my system run Diablo 4?" → Enhanced compatibility check with Steam Compare UI
"Check compatibility for Cyberpunk 2077" → Full compatibility analysis with optimization tips
"What are my system specs?" → Gaming-focused hardware detection with performance assessment
"Compare Cyberpunk vs Elden Ring" → Multi-game performance comparison

📦 G-Assist Plugin Installation

Ready-to-Use Executable

The G-Assist plugin is available as a pre-built executable in the root directory:

Executable: plugin.exe - Ready for G-Assist installation
Installer: install_plugin.bat - Automated installation script

Quick Installation

# Run the automated installer
.\install_plugin.bat

# This will:
# 1. Create %USERPROFILE%\canrun\ directory
# 2. Copy canrun-g-assist-plugin.exe and required files
# 3. Install data files and dependencies
# 4. Test the plugin functionality

🚀 READY FOR G-ASSIST INTEGRATION

Next Steps for Users:

Rebuild Plugin: pyinstaller --onefile --name plugin --distpath . plugin.py
Install Plugin: .\install_plugin.bat (as Administrator)
Test with G-Assist: "Hey canrun, can I run Diablo 4?"

🤖 MCP Server Functionality (NEW!)

CanRun now includes a full-featured Model Context Protocol (MCP) server that allows G-Assist to directly integrate with the CanRun compatibility engine. This provides seamless AI-assisted game compatibility checking through the official NVIDIA MCP standard.

MCP Tools and Capabilities

The MCP server exposes the following tools to G-Assist:

check_game_compatibility: Analyze if a specific game can run on the current system
- Input: Game name (e.g., "Diablo 4")
- Output: Detailed compatibility analysis with performance tier
detect_hardware: Provides comprehensive hardware detection for gaming systems
- Output: Detailed hardware specifications focused on gaming performance

Running the MCP Server

# Start the MCP server with auto port discovery
python app.py

# The server will be available at:
# http://localhost:xxxx (where xxxx is an available port)

G-Assist MCP Integration

G-Assist can automatically discover and use the CanRun MCP server when both are running. This enables advanced conversational interactions like:

"G-Assist, ask CanRun if I can play Starfield"
"G-Assist, check if my system meets Diablo 4 requirements"
"G-Assist, what's my gaming hardware like?"

✨ Key Features

🎯 RTX/GTX Optimized: Exclusively designed for RTX/GTX systems with G-Assist integration
🎮 CANRUN! Indicator: Instant visual feedback when your system meets game requirements
⭐ S-A-B-C-D-F Tier System: Advanced performance classification with weighted scoring (GPU 60%, CPU 25%, RAM 15%)
🧠 AI-Powered Analysis: Leverages G-Assist's embedded 8B Llama model for intelligent insights
🔒 Privacy-by-Design: All processing happens locally on your RTX GPU—no data leaves your system
🎯 Steam-First Data: Prioritizes Steam API for most up-to-date game requirements
🎯 Intelligent Game Matching: Advanced fuzzy matching handles game name variations
📊 Smart Performance Prediction: Comprehensive hardware hierarchies with RTX 30/20 series support
💡 Intelligent Recommendations: AI-generated optimization tips, DLSS strategies, upgrade suggestions
🏃 Zero Setup: Drop-in plugin with automatic RTX/GTX validation

🧪 Running Tests

Primary Test Command (Recommended):

# Run all tests with pytest
uv run python -m pytest test/ -v

# Test official G-Assist protocol specifically
python test/test_official_g_assist_protocol.py

# Test enhanced G-Assist communication
uv run python test/test_enhanced_g_assist_communication.py

Test Coverage:

✅ Advanced Performance Assessment: S-A-B-C-D-F tier system with weighted scoring
✅ LLM Analysis: 20/20 tests passing - G-Assist integration, privacy protection
✅ Steam API Integration: 15/15 tests passing - Real-time requirements fetching
✅ Hardware Detection: Fixed Windows 11, display resolution, NVIDIA driver detection
✅ MCP Server: Verified Model Context Protocol implementation

🏗️ G-Assist Integration (Official NVIDIA Protocol)

Current Integration Status: ✅ TESTING

Enhanced Plugin Configuration (v5.1)

{
  "manifestVersion": 1,
  "name": "CanRun Game Compatibility Checker - Enhanced",
  "version": "5.1.0",
  "executable": "python",
  "args": ["plugin.py"],
  "persistent": true,
  "functions": [
    {
      "name": "check_compatibility",
      "description": "Enhanced compatibility check with Steam Compare UI and performance analysis",
      "tags": ["game", "compatibility", "canrun", "can run", "will work", "diablo", "cyberpunk", "steam"]
    },
    {
      "name": "detect_hardware",
      "description": "Gaming-focused hardware detection with performance assessment",
      "tags": ["hardware", "specs", "system", "gpu", "cpu", "performance"]
    },
    {
      "name": "auto_detect",
      "description": "Automatic tool detection from natural language input",
      "tags": ["auto", "detect", "natural", "language", "smart"]
    }
  ]
}

Testing the Enhanced Integration

# Test enhanced compatibility check with Steam Compare UI
uv run python plugin.py --function check_compatibility --game "Diablo 4" --show-steam

# Test natural language auto-detection
uv run python plugin.py --function auto_detect --input "Can I run Elden Ring on my system?"

# Test gaming-focused hardware detection
uv run python plugin.py --function detect_hardware

# Expected: Enhanced G-Assist responses with rich formatting and Steam data

📁 Project Structure

canrun/
├── plugin.py                   # Main G-Assist Plugin (PRIMARY SUBMISSION)
├── app.py                      # Gradio UI and MCP Server implementation
├── manifest.json              # G-Assist function definitions with LLM integration
├── pyproject.toml             # Modern uv package manager configuration
├── requirements.txt           # Python dependencies
│
├── src/                        # Core modules with advanced tier system
│   ├── canrun_engine.py       # Main compatibility engine with S-A-B-C-D-F integration
│   ├── privacy_aware_hardware_detector.py # Enhanced hardware detection
│   ├── game_requirements_fetcher.py # Steam-first game requirements with fallbacks
│   ├── compatibility_analyzer.py # Analysis logic with tier classification
│   ├── dynamic_performance_predictor.py # Advanced S-A-B-C-D-F tier system
│   └── rtx_llm_analyzer.py    # G-Assist LLM integration module
│
├── data/                       # Static data files
│   ├── game_requirements.json  # Cached game requirements
│   └── gpu_hierarchy.json     # Comprehensive GPU/CPU performance hierarchies
│
├── test/                       # Comprehensive test suite
│   ├── test_official_g_assist_protocol.py # Official protocol verification
│   ├── test_enhanced_g_assist_communication.py # Enhanced communication tests
│   ├── test_hardware_detection.py
│   ├── test_compatibility_analysis.py
│   ├── test_performance_prediction.py
│   ├── test_llm_analysis.py   # LLM integration tests
│   └── test_steam_api_integration.py
│
├── LICENSE                     # Apache 2.0 license
├── README.md                  # This file
└── CHANGELOG.md              # Version history and updates

🔧 Technical Implementation

Core Components

1. Official G-Assist Protocol

# Official NVIDIA G-Assist communication protocol
- Input: {"tool_calls": [{"func": "function_name", "params": {...}}]}
- Output: {"success": true, "message": "..."}<<END>>
- Communication: Standard stdin/stdout (verified working)
- Mode Detection: stdin.isatty() check for G-Assist environment

2. Advanced Performance Assessment

# S-A-B-C-D-F tier system with weighted scoring
- GPU Performance: 60% weight (RTX 3080, RTX 3070, GTX 1660 Ti, etc.)
- CPU Performance: 25% weight (Intel i7-12700K, Ryzen 5 5600X, etc.)
- RAM Performance: 15% weight (16GB DDR4, 32GB DDR4, 8GB DDR4, etc.)
- Comprehensive hardware hierarchies with 50+ GPU/CPU models

3. Steam-First Requirements Fetching

# Prioritized data source architecture
- Primary: Steam Store API (real-time, most current)
- Fallback: Local cache (offline support, curated database)
- Privacy-protected data sanitization throughout
- Automatic game ID resolution and requirement parsing

4. MCP Server Implementation

# Model Context Protocol (MCP) server integration
- Uses Gradio for both UI and MCP server
- Async function support for real-time analysis
- Exposes game compatibility and hardware detection tools
- G-Assist direct integration capability

📊 Performance Tier Benchmarks

GPU Tier Classifications

S-Tier (95-100): RTX 4090, RTX 4080, RTX 3090 Ti
A-Tier (85-94): RTX 3080, RTX 3070 Ti, RX 6800 XT
B-Tier (75-84): RTX 3070, RTX 2080 Ti, RX 6700 XT
C-Tier (65-74): RTX 3060 Ti, RTX 2070, GTX 1080 Ti
D-Tier (55-64): RTX 3060, GTX 1660 Ti, RX 5600 XT
F-Tier (0-54): GTX 1050, GTX 960, older hardware

CPU Tier Classifications

S-Tier (95-100): Ryzen 9 5950X, Intel i9-12900K, Ryzen 7 5800X3D
A-Tier (85-94): Intel i7-12700K, Ryzen 7 5800X, Intel i9-11900K
B-Tier (75-84): Ryzen 5 5600X, Intel i5-12600K, Ryzen 7 3700X
C-Tier (65-74): Intel i5-11600K, Ryzen 5 3600, Intel i7-10700K
D-Tier (55-64): Intel i5-10400, Ryzen 5 2600, Intel i7-9700K
F-Tier (0-54): Intel i3 processors, older quad-cores

🛠️ Development and Contributing

Setting up Development Environment:

# Clone repository
git clone https://github.com/yourusername/canrun
cd canrun

# Install development dependencies
uv sync --dev

# Run tests to verify setup
uv run python -m pytest test/ -v

# Test official G-Assist protocol
python test/test_official_g_assist_protocol.py

Rebuilding the Executable:

# Rebuild the G-Assist plugin executable (required after code changes)
pyinstaller --onefile --name g-assist-plugin-canrun --distpath . --add-data "src;src" --add-data "data;data" --add-data "config.json;." plugin.py

# The executable is now available in the root directory as g-assist-plugin-canrun.exe
# This follows the official NVIDIA G-Assist naming convention: g-assist-plugin-<name>.exe
# This includes all dependencies and data files and can be used by G-Assist

📈 Version History

🎯 Current Status & Next Steps

🔄 Pending (Requires G-Assist Environment)

Live G-Assist Testing: Requires NVIDIA G-Assist installation for final verification
Function Trigger Validation: Test "canrun diablo4?" voice commands
Plugin Discovery Verification: Confirm G-Assist finds and loads the plugin
MCP Integration Testing: Verify G-Assist can discover and use the MCP server

📋 Technical Summary

CanRun has been successfully transformed from F-tier (49/100) to A-tier (92/100) performance and now implements the official NVIDIA G-Assist communication protocol and MCP server functionality. The plugin is ready for G-Assist integration testing.

Key Achievements:

✅ Enhanced Game Display: Clear identification of both search query and matched game
✅ Accurate Hardware Analysis: VRAM estimation and RAM tolerance for better compatibility assessment
✅ Steam API Integration: Real-time game requirements with accurate name matching
✅ Dynamic Performance Prediction: RTX 3080 = A-tier with comprehensive GPU/CPU models
✅ Robust Error Handling: Comprehensive timeout and error management
✅ Modern UI Standards: Updated Gradio interface with improved formatting
✅ MCP Server Implementation: Official Model Context Protocol support for AI agent integration

Ready to see if your system can run any game? CanRun delivers A-tier performance analysis with official G-Assist protocol support!

For technical support, feature requests, or contributions, visit GitHub repository.