Hugging Face's logo

Spaces:
BryanBradfo
/
CoachDeepBlue
Sleeping

App Files Community
CoachDeepBlue / README.md
BryanBradfo's picture
BryanBradfo
Update README.md
9ebd598 verified
preview code
|
raw
history blame contribute delete
7.29 kB
metadata
title: Coach Deep Blue
emoji: ♟️
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: true
tags:
  - mcp-in-action-track-consumer
  - building-mcp-track-consumer
  - mcp
  - agent
  - chess
  - openai
  - stockfish
short_description: Omniscient MCP Chess Agent for real-time voice coaching

Coach Deep Blue - MCP Agent

Recreating the Legend.

Deep Blue AI is a fully autonomous, voice-enabled chess agent that connects a Large Language Model (OpenAI) with powerful local tools via the Model Context Protocol (MCP) pattern.

Unlike standard chatbots that hallucinate chess moves, Deep Blue never guesses. It uses Tools to perceive reality, calculate the optimal path, and verbally coach the player.

🎥 Video Demonstration 📢 Social Media Post

🚨🟡🌍 IMPORTANT NOTICE FOR HACKATHON! 🤖♟️🚨

🏆 Goal: This project demonstrates the power of MCP (Model Context Protocol) in a real-world consumer application. We prove that giving an LLM access to specialized tools (Engine + Database) creates a "Super-Intelligence" capable of reasoning far beyond the model's native training data.

🙏 Support: If you enjoy the strategic depth and the robotic persona of Deep Blue, please give this Space a Like (❤️)! Your support helps us push the boundaries of Agentic AI in gaming.

🌐 Project Overview

Deep Blue AI is not just a chess interface; it's an Intelligent Orchestrator. It leverages a multi-tool architecture to perform complex strategic analysis in real-time:

  • 🤖 The Agent (Deep Blue): A Persona-driven LLM that orchestrates the tools, synthesizes data, and communicates with the user via a cold, analytical voice.
  • 🧠 The Engine (Stockfish 16): Provides ground-truth calculation and tactical evaluation.
  • 📚 The Library (Lichess DB): Provides theoretical knowledge of over 2 million opening positions.
  • 👁️ The Eye (Tactical Analyzer): A custom semantic tool that translates board states into human concepts (Pins, Forks, Checks).

🛠️ MCP Architecture & Tools

Our agent follows the Model Context Protocol principles. The LLM does not "play" chess; it queries tools to understand the game state.

1. ⚡ Tool: Stockfish 16 Engine (The Calculator)

  • Purpose: Pure calculation and optimal move generation.
  • Implementation: Running as a local binary within the Docker container via UCI Protocol.
  • Usage:
    • Calculates evaluations in Centipawns (CP).
    • Detects forced mates sequences.
    • Generates the "Optimal Path" (PV - Principal Variation).

2. 📚 Tool: Lichess Opening Database (The Knowledge)

  • Purpose: Contextualizing the game phase.
  • Data Source: A local compilation of Lichess master games compressed into TSV files (2M+ opening variations (TSV Lookup))
  • Usage:
    • Identifies the exact opening name (e.g., "Sicilian Defense: Najdorf Variation").
    • Allows the Agent to switch strategy based on opening theory.

3. 🔍 Tool: Tactical Analyzer (The Semantic Layer)

  • Purpose: Translating raw board data into semantic concepts the LLM can explain.
  • Logic: Custom Python algorithms using python-chess.
  • Usage:
    • Material Scan: Prevents hallucinations by listing exact remaining pieces.
    • Pattern Recognition: Detects pins, checks, and material imbalances programmatically.

4. 🗣️ Tool: OpenAI TTS-1 (The Voice)

  • Purpose: Real-time verbal feedback.
  • Configuration: Uses the onyx model for a deep, robotic, and authoritative tone suitable for a supercomputer persona.
  • Speed: Tuned to 1.15x for dynamic, fluid interaction.

📦 Data Integration Logic (The "Brain")

When a user makes a move or asks a question via microphone, the system triggers the following MCP Workflow:

  1. Perception: The board FEN (Forsyth–Edwards Notation) is extracted.
  2. Tool Execution:
    • tool_engine_analysis(board) -> Returns Score & Best Move Coordinates.
    • tool_get_opening(board) -> Returns Opening Name.
    • analyze_tactics(board) -> Returns Semantic Threats (e.g., "King is in check").
  3. Context Construction: All tool outputs are aggregated into a structured system prompt.
  4. Reasoning: The LLM (GPT-4o-mini) processes the telemetry. It is strictly forbidden from inventing moves; it must interpret the tool outputs.
  5. Response: The Agent outputs a strategic explanation and an audio file is generated.

✨ Key Features

🛡️ Anti-Hallucination Protocol

Standard LLMs often play illegal moves (e.g., "Bishop to h9"). Deep Blue AI uses a Coordinate System (e.g., e2 -> e4) validated by the engine. It explicitly lists the material on the board to the LLM at every turn to ensure grounding.

🎤 Human Interface (Voice & Chat)

  • Listen: Deep Blue speaks every piece of advice.
  • Speak: Use the Microphone to ask questions like "Why is my position bad?" or "What if I sacrifice my Rook?". The Agent will use its tools to verify your idea and answer.

💻 Cyberpunk UI

A custom CSS interface designed to mimic a high-tech terminal, featuring:

  • Tactical Log: A scrollable history of optimal moves.
  • Visual Illumination: Textual highlighting of the recommended move (e.g., ♞ g1 ➔ f3).
  • Dynamic Feedback: Real-time updates on game status (Checkmate celebrations included 🎉).

🚀 How to Use

  1. Launch the App: Wait for the Docker container to build (it installs Stockfish and downloads the DB).
  2. API Key:
    • Enter your OpenAI API Key in the right column (or use the system key if provided).
    • Note: Your key is used only for this session and is not stored.
  3. Play White: Make your move on the board.
  4. Listen & Learn: Deep Blue will analyze your move and dictate the optimal response.
  5. Interact: Stuck? Click the Microphone, ask a question, and click "QUERY SYSTEM".

🏆 Hackathon Tracks

We are submitting this project under the following tracks:

  • 🤖 Track 2: MCP in Action (Consumer)
    • Why? We demonstrate a complete, consumer-facing application where the AI Agent autonomously plans, reasons, and executes tasks using a suite of local MCP tools (Engine, DB, Python Logic).
  • 🔧 Track 1: Building MCP (Consumer)
    • Why? We built custom tool integrations that bridge raw binary outputs (Stockfish UCI) with semantic LLM understanding, effectively creating "The Chess Toolset" for Agents.
  • 🧠 OpenAI Category Award
    • Why? Extensive integration of GPT-4o-mini for reasoning and OpenAI TTS-1 for real-time voice interaction.

🧑‍💻 Credits

  • Author: BryanBradfo
  • Tech Stack: Hugging Face Spaces (Docker), Gradio, Python-Chess, Stockfish, OpenAI.
  • Special Thanks: To the Gradio team for the gradio_chessboard component and the Lichess community for the open database.

Note: This project runs in a Docker environment to ensure access to the Stockfish binary and system-level audio dependencies.