feat: Add Gemma3-cpp integration scaffold with automated setup and flexible build system

[Copilot]

Overview

Resolves #62 by implementing a complete project scaffold for Google Gemma3.cpp integration with FazAI, enabling native local AI inference with flexible setup options and graceful degradation.

Problem

The FazAI worker previously relied on hardcoded, user-specific paths (/home/rluft/gemma.cpp) for Gemma integration, making it difficult for other developers to:

• Build the worker without manually setting up gemma.cpp
• Understand how to integrate the Gemma library
• Deploy in different environments
• Contribute to the project

Additionally, builds would fail entirely if gemma.cpp was unavailable, with no fallback mechanism.

Solution

This PR introduces a comprehensive integration scaffold with three key components:

1. Automated Setup Script (worker/setup_gemma.sh)

A one-command solution that:

• Clones Google's official gemma.cpp repository
• Initializes all required submodules
• Builds the library with optimizations (Release mode, position-independent code)
• Creates static library libgemma.a
• Generates CMake configuration files

Usage:

cd worker
./setup_gemma.sh

2. Flexible Build System

Updated CMakeLists.txt to support multiple gemma.cpp locations with automatic detection:

• third_party/gemma.cpp/ (preferred, cloned by setup script)
• Environment variable GEMMA_CPP_ROOT
• Pre-built library in lib/libgemma.a
• Legacy path /home/rluft/gemma.cpp (backward compatibility)

The build system now:

• Provides informative warnings when gemma.cpp is not found
• Offers clear instructions for setup
• Falls back to stub implementations for development/testing
• Never fails - always produces a working binary

3. Comprehensive Documentation

Three-tier documentation approach:

Quick Start (GEMMA_QUICKSTART.md)

• TL;DR commands
• Common scenarios
• Fast troubleshooting

Complete Guide (worker/GEMMA_INTEGRATION.md)

• Detailed setup instructions (automated, manual, pre-built)
• Configuration and model download
• Performance optimization tips
• Comprehensive troubleshooting
• Upgrade path to Gemma 3.x

Worker Documentation (worker/README.md)

• Architecture overview
• Build options and testing
• Development guidelines

Key Features

✅ Zero Configuration for New Users - Single script handles entire setup
✅ Multiple Build Modes - Native, pre-built library, or stub fallback
✅ Graceful Degradation - Worker builds successfully even without gemma.cpp
✅ Clear Feedback - Informative messages guide users through setup
✅ Backward Compatible - Existing workflows continue to work
✅ Future-Proof - Ready for Gemma 2.x and 3.x models

Build Modes

Native Gemma (Recommended)

cd worker
./setup_gemma.sh  # Downloads and builds gemma.cpp
./build.sh        # Builds with native Gemma support

Pre-built Library

cp /path/to/libgemma.a worker/lib/
cd worker
./build.sh

Stub Mode (Development)

cd worker
./build.sh  # Answer 'y' when prompted to continue without Gemma

Testing Results

All tests passed successfully:

• ✅ Build without gemma.cpp - Successfully builds 331KB worker binary with stubs
• ✅ CMake detection - Correctly identifies and reports gemma.cpp availability
• ✅ Informative messages - Clear guidance provided when setup needed
• ✅ Backward compatibility - Legacy paths continue to work

Example build output without gemma.cpp:

CMake Warning at CMakeLists.txt:84 (message):
  gemma.cpp not found. Worker will be built without native Gemma support.

-- To enable Gemma support:
--   1. Run: ./setup_gemma.sh
--   2. Or set GEMMA_ROOT environment variable
--   3. Or place libgemma.a in lib/ directory
-- Building worker with stub implementations (no native Gemma)
[100%] Built target fazai-gemma-worker

Changes

New Files

• worker/setup_gemma.sh - Automated setup script (211 lines)
• worker/GEMMA_INTEGRATION.md - Complete integration guide (327 lines)
• worker/README.md - Worker documentation (222 lines)
• worker/third_party/README.md - Third-party dependencies guide (46 lines)
• GEMMA_QUICKSTART.md - Quick reference guide (132 lines)
• .github/ISSUE_62_RESOLUTION.md - Implementation summary (179 lines)

Updated Files

• worker/CMakeLists.txt - Flexible path detection and stub fallback (+84 lines)
• worker/build.sh - Enhanced checks and user guidance (+50 lines)
• .gitignore - Exclude gemma.cpp source and build artifacts
• README.md - Add Gemma3 integration section
• CHANGELOG.md - Document changes

Statistics

• 11 files changed
• +1,296 lines added, -32 lines removed
• Zero breaking changes

Migration Guide

For existing users, no changes required - the system maintains backward compatibility. To adopt the new setup:

1. Remove old gemma.cpp (optional): rm -rf /home/rluft/gemma.cpp
2. Run setup script: cd worker && ./setup_gemma.sh
3. Rebuild worker: ./build.sh

Models can be downloaded from Kaggle:

• gemma-2b-it - 2B parameters, instruction-tuned (4GB RAM)
• gemma-7b-it - 7B parameters, instruction-tuned (14GB RAM)
• gemma3-1b-it - Latest 1B model (2GB RAM)

Documentation

• Quick Start Guide - Start here for fast setup
• Complete Integration Guide - Detailed documentation
• Worker README - Architecture and development
• Resolution Summary - Full implementation details

Related

• Closes Project scaffold and Gemma3-cpp integration #62
• Related: Google gemma.cpp
• Models: Kaggle Gemma Models

Original prompt

Resolva @RLuf/FazAI/issues/62

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.