[WIP] Implement Lc0-compatible neural network inference for MCTS

[Copilot]

• Analyze existing repository structure and understand MCTS/GPU implementations
• Create src/nn/ directory for neural network components
• Implement weight loading from Lc0 protobuf format (.pb and .pb.gz)
• Implement position encoding (112-plane format)
• Implement policy tables mapping UCI moves to NN indices
• Create Metal backend for transformer inference using MPSGraph
• Create NNMCTSEvaluator to bridge MCTS and neural network
• Update CMakeLists.txt to include new neural network components
• Create verification test suite (tests/test_nn_comparison.cpp)
• Run code review and security checks

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature] Implement Lc0-compatible neural network inference for MCTS with Metal backend</issue_title>
<issue_description>## Summary

Implement neural network inference for MetalFish's MCTS search that uses Lc0-format network weights (.pb files) and produces identical results to Lc0 for the same positions. The implementation should be heavily optimized for Apple Silicon's unified memory architecture.

Background

MetalFish currently has a working MCTS implementation (src/mcts/thread_safe_mcts.cpp) that uses NNUE evaluation. To achieve stronger play, we need to integrate transformer-based neural network evaluation similar to Lc0 (Leela Chess Zero).

We have:

• Network weights: networks/BT4-1024x15x32h-swa-6147500.pb (365MB transformer network)
• Reference implementation: the official Lc0 source code
• Target platform: Apple Silicon Macs (M1/M2/M3/M4) with Metal GPU acceleration

Implementation Strategy: Copy from Lc0

Lc0 is open source (GPL-3.0). You are encouraged to directly copy entire code files from reference/lc0/ using cp or mv commands. Do not rewrite from scratch what already exists.

Copyright Header Requirement

All copied files MUST have their copyright headers replaced with the MetalFish header:

/*
  MetalFish - A GPU-accelerated UCI chess engine
  Copyright (C) 2025 Nripesh Niketan

  Licensed under GPL-3.0
*/

Namespace and Naming Requirements (CRITICAL)

There must be NO mention of "lc0", "lczero", "leela", or "Leela" anywhere in the final code.

This includes:

• ❌ Namespaces: lczero:: → ✅ MetalFish:: or MF::
• ❌ Class names: Lc0Network → ✅ NeuralNetwork
• ❌ Function names: lc0_encode() → ✅ encode_position()
• ❌ Variable names: lc0_weights → ✅ nn_weights
• ❌ Comments: // Lc0-style encoding → ✅ // Position encoding
• ❌ File names: lc0_backend.cpp → ✅ nn_backend.cpp
• ❌ Macros: LC0_API → ✅ METALFISH_API or remove
• ❌ Include guards: LC0_NEURAL_H → ✅ METALFISH_NN_H

Example transformation:

// BEFORE (Lc0 original)
namespace lczero {
class Lc0Network {
  void Lc0Encode(const lczero::Position& pos);
};
}  // namespace lczero

// AFTER (MetalFish)
namespace MetalFish {
namespace NN {
class Network {
  void encode(const Position& pos);
};
}  // namespace NN
}  // namespace MetalFish

Directory Guidelines

DO:

• Copy files into our existing directory structure (src/nn/, src/mcts/, src/gpu/)
• Create sensible new directories if needed (e.g., src/nn/, src/nn/metal/)
• Maintain a clean, professional codebase structure

DO NOT:

• Create directories like lc0_implementation/, lc0_copy/, external_lc0/
• Keep Lc0-specific directory structures that don't fit our layout
• Leave Lc0 copyright headers in any file
• Leave any lczero:: namespace references

Example Workflow

# Copy protobuf definitions
cp reference/lc0/src/neural/network.h src/nn/network.h
cp reference/lc0/src/neural/encoder.cc src/nn/encoder.cpp

# Copy Metal backend
cp reference/lc0/src/neural/metal/*.mm src/nn/metal/

# Then for EACH copied file:
# 1. Replace copyright header with MetalFish header
# 2. Change namespace lczero:: to MetalFish::NN::
# 3. Rename any Lc0-prefixed classes/functions
# 4. Update all comments to remove Lc0 references
# 5. Update include guards

Files to Consider Copying

From reference/lc0/src/:

• neural/network.h - Network interface
• neural/encoder.cc - Position encoding (112 planes)
• neural/writer.cc - Protobuf parsing
• neural/metal/ - Metal backend (MPSGraph)
• mcts/node.cc - MCTS node structure
• mcts/search.cc - Search algorithms
• chess/board.cc - Board representation (for encoding compatibility)
• utils/weights_adapter.cc - Weight loading utilities

Requirements

1. Neural Network Components

Create src/nn/ directory with:

• Weight Loading (loader.h, loader.cpp)

  • Parse Lc0 protobuf format (.pb and .pb.gz)
  • Extract transformer weights, policy head, value head, moves-left head
  • Support for BT4 (Big Transformer 4) architecture

• Position Encoding (encoder.h, encoder.cpp)

  • Encode chess positions into 112-plane input format (identical to Lc0)
  • 8 history positions × 13 planes + 8 auxiliary planes
  • Handle board flipping for black-to-move positions
  • Support canonical format transformations

• Policy Tables (policy_tables.h, policy_tables.cpp)

  • Map between UCI moves and neural network policy indices
  • 1858 policy outputs for standard chess
  • Attention policy map for transformer networks

• Metal Backend (metal/ or nn/metal/)

  • Use MPSGraph for transformer inference
  • Optimize for unified memory (zero-copy between CPU/GPU)
  • Support batch inference for MCTS

2. MCTS Integration

Update src/mcts/:
...

• Fixes [Feature] Implement Lc0-compatible neural network inference for MCTS with Metal backend #14

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.