Overview: Why Offline-First Edge AI Matters in Africa

[ Farmer / User in the Field (Airplane Mode ON) ]
       │
       ├── 1. Captures Leaf Photo OR Asks Question (Text / Offline Voice)
       ▼
┌──────────────────────────────────────────────────────────────────────┐
│ 1. LOCAL RAG ENGINE (SQLite FTS5 + BM25 Ranking)                     │
│ - Searches indexed FAO & IITA agronomic manuals in <2ms (0 MB RAM)   │
│ - Extracts verified pathogen symptoms, organic dosages & seasons     │
└──────────────────────────────┬───────────────────────────────────────┘
                               │ 2. Injects Factual Grounding Context
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│ 2. ON-DEVICE GEMMA ENGINE (flutter_gemma + LiteRT-LM Runtime)        │
│ - GemmaEngineManager: Single-threaded FFI Mutex + 8s Timeout Lock    │
│ - Vision VLM Mode: 512px image + 4096 maxTokens + Early-Exit Filter  │
│ - Chat Assistant Mode: 2048 maxTokens + 5-message Sliding Window     │
└──────────────────────────────┬───────────────────────────────────────┘
                               │ 3. Streams Sanitized Tokens
                               ▼
┌──────────────────────────────────────────────────────────────────────┐
│ 3. FLUTTER BLoC / CUBIT LAYER & AUTONOMOUS ACTIONS                   │
│ - Real-time LaTeX/Emoji Sanitizer (converts $NaHCO_3$ -> plain text) │
│ - Autonomous Function Calling (pauses/resumes SQLite rain calendar)  │
│ - Offline TTS Readout & Farm Health PDF Export                       │
└──────────────────────────────────────────────────────────────────────┘

flutter create --org com.gemmea gemmea
cd gemmea
mkdir -p lib/core/services lib/core/utils lib/data/datasources lib/data/repositories

flutter create --org com.gemmea gemmea
cd gemmea
New-Item -ItemType Directory -Force -Path lib/core/services, lib/core/utils, lib/data/datasources, lib/data/repositories

lib/
├── core/
│   ├── services/
│   │   └── gemma_engine_manager.dart    # Step 4: Native FFI Mutex & Hot-Reload Lock
│   └── utils/
│       └── text_sanitizer.dart          # Step 7: Real-time LaTeX & Emoji Sanitizer
├── data/
│   ├── datasources/
│   │   ├── gemma_local_source.dart      # Step 5: 512px Vision VLM & Early-Exit Guardrail
│   │   └── sqlite_helper.dart           # Step 6: Zero-RAM SQLite FTS5 + BM25 Local RAG
│   └── repositories/
│       └── chat_repository_impl.dart    # Steps 3 & 7: Atomic .tmp Download & Token Stream
└── main.dart                            # Step 9: Minimal Runnable UI (Download + Scan + Chat)

name: gemmea
description: "Offline-first AI agronomic assistant powered by Google Gemma & SQLite FTS5 RAG."
publish_to: 'none'
version: 0.1.0+1

environment:
  sdk: '>=3.5.0 <4.0.0'

dependencies:
  flutter:
    sdk: flutter

  # On-Device LLM Runtime (MediaPipe / LiteRT-LM Native Bindings)
  flutter_gemma: ^1.2.3
  flutter_gemma_litertlm: ^1.1.0

  # Local FTS5 RAG Database & Atomic Model File Management
  sqflite: ^2.4.3
  path: ^1.9.1
  path_provider: ^2.1.6
  http: ^1.2.1

  # Multimodal Camera / Gallery Input
  image_picker: ^1.1.2

dev_dependencies:
  flutter_test:
    sdk: flutter
  flutter_lints: ^5.0.0

flutter:
  uses-material-design: true

    defaultConfig {
        applicationId = "com.gemmea.gemmea"
        // MediaPipe / LiteRT-LM native .so libraries require minSdk 26+
        minSdk = 26
        targetSdk = flutter.targetSdkVersion
        versionCode = flutter.versionCode
        versionName = flutter.versionName
    }

<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.CAMERA" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

    <application
        android:label="Gemmea"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">
        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:launchMode="singleTop"
            android:taskAffinity=""
            android:theme="@style/LaunchTheme"
            android:configChanges="orientation|keyboardHidden|keyboard|screenSize|smallestScreenSize|locale|layoutDirection|fontScale|screenLayout|density|uiMode"
            android:hardwareAccelerated="true"
            android:windowSoftInputMode="adjustResize">
            <meta-data
              android:name="io.flutter.embedding.android.NormalTheme"
              android:resource="@style/NormalTheme"
              />
            <intent-filter>
                <action android:name="android.intent.action.MAIN"/>
                <category android:name="android.intent.category.LAUNCHER"/>
            </intent-filter>
        </activity>
        <meta-data
            android:name="flutterEmbedding"
            android:value="2" />
    </application>
</manifest>

Future<bool> checkModelInstalled() async {
  final directory = await getApplicationDocumentsDirectory();
  final litertlmFile = File('${directory.path}/gemma.litertlm');
  final binFile = File('${directory.path}/gemma.bin');

  // Auto-migrate legacy gemma.bin to gemma.litertlm if already on the user's phone
  if (await binFile.exists() && !await litertlmFile.exists()) {
    await binFile.rename(litertlmFile.path);
  }
  return await litertlmFile.exists();
}

Future<void> initializeGemma(Function(double) onProgress) async {
  return GemmaEngineManager.runWithLock(() async {
    await GemmaEngineManager.ensureInitialized();

    final directory = await getApplicationDocumentsDirectory();
    final modelFile = File('${directory.path}/gemma.litertlm');
    final tempModelFile = File('${directory.path}/gemma.litertlm.tmp');

    if (!await modelFile.exists()) {
      // 1. Clean up any incomplete .tmp file from an interrupted download
      if (await tempModelFile.exists()) {
        await tempModelFile.delete();
      }

      // 2. Fast 4-second DNS check before opening the download stream
      final result = await InternetAddress.lookup('google.com')
          .timeout(const Duration(seconds: 4));
      if (result.isEmpty || result.first.rawAddress.isEmpty) {
        throw const SocketException('Internet connection is required for first-time setup.');
      }

      const url = 'https://huggingface.co/litert-community/'
          'gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm';
      final client = http.Client();

      try {
        final request = http.Request('GET', Uri.parse(url));
        final response = await client.send(request);
        if (response.statusCode != 200) {
          throw HttpException('Download failed (HTTP ${response.statusCode})');
        }

        final contentLength = response.contentLength ?? 0;
        int downloadedBytes = 0;

        // 3. Stream chunks directly to disk via IOSink (Zero RAM bloat)
        final IOSink sink = tempModelFile.openWrite();
        await response.stream.forEach((chunk) {
          downloadedBytes += chunk.length;
          sink.add(chunk);
          if (contentLength > 0) {
            onProgress(downloadedBytes / contentLength);
          }
        });
        await sink.close();

        // 4. ATOMIC RENAME: Only promote to gemma.litertlm upon 100% completion
        if (await tempModelFile.exists()) {
          await tempModelFile.rename(modelFile.path);
        }
      } catch (e) {
        if (await tempModelFile.exists()) await tempModelFile.delete();
        rethrow;
      } finally {
        client.close();
      }
    }

    // 5. Register the verified local file with FlutterGemma's LiteRT-LM runtime
    await FlutterGemma.installModel(
      modelType: ModelType.gemmaIt,
      fileType: ModelFileType.litertlm,
    ).fromFile(modelFile.path).install();
  });
}

import 'dart:async';
import 'dart:developer' as dev;
import 'package:flutter_gemma/flutter_gemma.dart';
import 'package:flutter_gemma_litertlm/flutter_gemma_litertlm.dart';

class GemmaEngineManager {
  static bool _isInitialized = false;
  static Completer<void>? _initCompleter;
  static Future<void>? _activeExecution;
  static Function()? _onResetChatCallback;

  static bool get isInitialized => _isInitialized;
  static bool get isBusy => _activeExecution != null;

  static void setResetChatCallback(Function() callback) {
    _onResetChatCallback = callback;
  }

  static void resetChatSession() {
    _onResetChatCallback?.call();
  }

  /// Force clears stale lock state and resets chat session on Hot Reload or FFI error
  static void forceResetLockState() {
    dev.log("Force resetting GemmaEngineManager lock state & session handles.");
    _activeExecution = null;
    _initCompleter = null;
    resetChatSession();
  }

  static Future<void> ensureInitialized() async {
    if (_isInitialized) return;
    if (_initCompleter != null) return _initCompleter!.future;

    _initCompleter = Completer<void>();
    try {
      await FlutterGemma.initialize(
        inferenceEngines: const [LiteRtLmEngine()],
      );
      _isInitialized = true;
      _initCompleter!.complete();
    } catch (e) {
      // Native FFI engine already bound across Hot Reload
      _isInitialized = true;
      if (!(_initCompleter?.isCompleted ?? true)) _initCompleter!.complete();
    } finally {
      _initCompleter = null;
    }
  }

  /// Wraps a Future operation to guarantee single-threaded execution on LiteRT-LM
  static Future<T> runWithLock<T>(Future<T> Function() action) async {
    final previousExecution = _activeExecution;
    final completer = Completer<void>();
    _activeExecution = completer.future;

    if (previousExecution != null) {
      try {
        await previousExecution.timeout(const Duration(seconds: 8));
      } on TimeoutException {
        forceResetLockState();
      } catch (_) {}
    }

    try {
      return await action();
    } catch (e) {
      if (e.toString().contains("channel-error") ||
          e.toString().contains("PlatformException") ||
          e.toString().contains("Null")) {
        forceResetLockState();
      }
      rethrow;
    } finally {
      completer.complete();
      if (_activeExecution == completer.future) _activeExecution = null;
    }
  }

  /// Wraps a Stream operation with the same FFI mutex & deadlock protection
  static Stream<T> runStreamWithLock<T>(Stream<T> Function() streamFactory) async* {
    final previousExecution = _activeExecution;
    final completer = Completer<void>();
    _activeExecution = completer.future;

    if (previousExecution != null) {
      try {
        await previousExecution.timeout(const Duration(seconds: 8));
      } on TimeoutException {
        forceResetLockState();
      } catch (_) {}
    }

    try {
      await for (final value in streamFactory()) {
        yield value;
      }
    } catch (e) {
      if (e.toString().contains("channel-error") ||
          e.toString().contains("PlatformException")) {
        forceResetLockState();
      }
      rethrow;
    } finally {
      completer.complete();
      if (_activeExecution == completer.future) _activeExecution = null;
    }
  }
}

import 'dart:io';
import 'dart:typed_data';
import 'dart:ui' as ui;
import 'package:flutter_gemma/flutter_gemma.dart';
import 'package:gemmea/core/services/gemma_engine_manager.dart';
import 'package:gemmea/core/utils/text_sanitizer.dart';
import 'package:gemmea/data/datasources/sqlite_helper.dart';

class GemmaLocalSourceImpl {
  Future<String> evaluateCropImage(File imageFile, String prompt) async {
    return GemmaEngineManager.runWithLock(() async {
      GemmaEngineManager.resetChatSession();
      try {
        await GemmaEngineManager.ensureInitialized();
        final rawBytes = await imageFile.readAsBytes();

        // 1. Downsample to 512px max width to prevent native OOM crashes
        final imageBytes = await _optimizeImageBytes(rawBytes);

        // 2. Fetch grounded FAO/IITA context from local SQLite FTS5
        final faoContext = await _fetchRagContextFromSqlite(imageFile.path, prompt);

        // 3. Prefer CPU backend on budget devices whose GPUs lack OpenCL vision buffers
        InferenceModel model;
        try {
          model = await FlutterGemma.getActiveModel(
            supportImage: true,
            maxTokens: 4096,
            preferredBackend: PreferredBackend.cpu,
          );
        } catch (_) {
          model = await FlutterGemma.getActiveModel(
            supportImage: true,
            maxTokens: 4096,
          );
        }

        final session = await model.createSession();

        // 4. Multimodal VLM Prompt with Step 1 Early-Exit Short-Circuit (in English)
        final vlmPrompt = '''
You are Gemmea, the offline AI agronomist for crop health diagnosis in East Africa.
Examine the provided image carefully.

ABSOLUTE AND URGENT RULE (IMMEDIATE EVALUATION):
Step 1: Look at the image. If it is NOT a plant leaf or agricultural crop
(e.g., human face, phone, shoe, furniture, animal, non-plant object):
Immediately STOP all generation and reply ONLY with this exact sentence:
"The captured image does not appear to be a plant leaf. Please retake a photo clearly targeting a leaf from your crop."
DO NOT GENERATE ANY HEADINGS AND DO NOT USE THE RAG CONTEXT BELOW.

Step 2: IF AND ONLY IF THE IMAGE IS GENUINELY A PLANT LEAF OR CROP:
Provide a detailed, structured agronomic analysis organized into these 7 sections (NO EMOJIS):

### 1. PRIMARY DIAGNOSIS & HYPOTHESES
- Crop: [Exact crop observed: Maize, Cassava, Bean, Banana, Tomato, Coffee, or Unknown]
- Disease: [If healthy, write EXPLICITLY: "No disease (Healthy Leaf)". If diseased, state exact pathogen/disease name]
- Confidence Level: [e.g., 90%]
- Differential Diagnoses: [Environmental or secondary factors if applicable]
### 2. DETAILED OBSERVED SYMPTOMS
(Chlorosis, pustules, mosaic patterns, curling, necrotic streaks, or intact lamina).
### 3. CAUSES & VECTORS (IITA STANDARDS)
(Pathogen agent and transmission vector such as Bemisia tabaci whitefly or Xanthomonas).
### 4. STEP-BY-STEP ORGANIC REMEDIES & TREATMENT
(Local bio-remedies: Neem leaf extract 200g/L, wood ash, baking soda NaHCO3 5g/L with black soap, Tithonia liquid manure).
### 5. SOIL MANAGEMENT, NUTRIENTS & IRRIGATION
(Drainage, composting, mulching, moisture control).
### 6. IMMEDIATE 3-STEP ACTION PLAN
(Step 1, Step 2, Step 3 for the farmer today).
### 7. OFFICIAL FAO & IITA REFERENCES
(Explicit citations from the local RAG context below).

REFERENCE RAG CONTEXT (IGNORE COMPLETELY IF NOT A PLANT):
$faoContext

User instruction: $prompt
''';

        await session.addQueryChunk(
          Message.withImage(
            text: vlmPrompt,
            imageBytes: imageBytes,
            isUser: true,
          ),
        );

        final String response = await session.getResponse();
        return TextSanitizer.cleanLatexAndFormatting(response);
      } finally {
        GemmaEngineManager.resetChatSession();
      }
    });
  }

  Future<String> _fetchRagContextFromSqlite(String imagePath, String prompt) async {
    try {
      final docs = await SQLiteHelper.instance.searchFAOKnowledge("$imagePath $prompt");
      if (docs.isEmpty) return "Standard East African FAO/IITA visual crop pathology guidelines.";
      return docs.map((d) {
        return "- ${d['topic']} (${d['crop_name']}): ${d['content']} "
               "Organic Remedy: ${d['organic_remedy']} (Source: ${d['source_citation']})";
      }).join("\n");
    } catch (_) {
      return "Standard East African FAO/IITA visual crop pathology guidelines.";
    }
  }

  Future<Uint8List> _optimizeImageBytes(Uint8List inputBytes) async {
    try {
      final codec = await ui.instantiateImageCodec(
        inputBytes,
        targetWidth: 512,
      );
      final frameInfo = await codec.getNextFrame();
      final image = frameInfo.image;
      final byteData = await image.toByteData(format: ui.ImageByteFormat.png);
      image.dispose(); // Crucial: release native C++ Skia/Impeller texture immediately!
      if (byteData != null) {
        return byteData.buffer.asUint8List();
      }
    } catch (_) {}
    return inputBytes;
  }
}

import 'package:path/path.dart';
import 'package:sqflite/sqflite.dart';

class SQLiteHelper {
  static final SQLiteHelper instance = SQLiteHelper._init();
  static Database? _database;

  SQLiteHelper._init();

  Future<Database> get database async {
    if (_database != null) return _database!;
    final dbPath = await getDatabasesPath();
    _database = await openDatabase(
      join(dbPath, 'gemmea.db'),
      version: 1,
      onCreate: _createDB,
    );
    return _database!;
  }

  Future<void> _createDB(Database db, int version) async {
    // 1. Irrigation Calendar table for Autonomous Function Calling
    await db.execute('''
      CREATE TABLE IF NOT EXISTS calendar (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        title TEXT NOT NULL,
        event_date TEXT NOT NULL,
        description TEXT NOT NULL,
        is_rainy INTEGER NOT NULL DEFAULT 0
      )
    ''');

    await db.insert('calendar', {
      'title': 'Cassava & Maize Irrigation',
      'event_date': DateTime.now().toIso8601String().split('T')[0],
      'description': 'Regular morning root-zone watering cycle.',
      'is_rainy': 0,
    });

    await _createFAOTables(db);
  }

  Future<void> _createFAOTables(Database db) async {
    // 2. Base table storing official FAO & IITA East African agronomic guidelines
    await db.execute('''
      CREATE TABLE IF NOT EXISTS fao_knowledge_base (
        id INTEGER PRIMARY KEY AUTOINCREMENT,
        topic TEXT NOT NULL,
        crop_name TEXT NOT NULL,
        keywords TEXT NOT NULL,
        content TEXT NOT NULL,
        organic_remedy TEXT NOT NULL,
        estimated_loss_pct REAL NOT NULL,
        source_citation TEXT NOT NULL
      )
    ''');

    // 3. SQLite FTS5 Virtual Table for sub-2ms BM25 full-text ranking
    try {
      await db.execute('''
        CREATE VIRTUAL TABLE IF NOT EXISTS fao_knowledge_fts USING fts5(
          topic, crop_name, keywords, content, organic_remedy, source_citation,
          content='fao_knowledge_base', content_rowid='id'
        )
      ''');

      // Trigger to keep FTS5 index automatically synchronized on insert
      await db.execute('''
        CREATE TRIGGER IF NOT EXISTS fao_ai AFTER INSERT ON fao_knowledge_base BEGIN
          INSERT INTO fao_knowledge_fts(
            rowid, topic, crop_name, keywords, content, organic_remedy, source_citation
          ) VALUES (
            new.id, new.topic, new.crop_name, new.keywords,
            new.content, new.organic_remedy, new.source_citation
          );
        END;
      ''');
    } catch (_) {
      // Fallback to weighted field scorer if custom OEM SQLite lacks FTS5
    }

    // 4. Seed verified East African FAO / IITA knowledge records
    final initialEntries = [
      {
        'topic': 'Cassava Mosaic Disease (CMD)',
        'crop_name': 'Cassava',
        'keywords': 'cassava manioc mosaic cmd leaf yellowing mottling curl whitefly bemisia',
        'content': 'Caused by a geminivirus transmitted by the whitefly (Bemisia tabaci). '
            'Symptoms: chlorotic yellow-green mosaic pattern, leaf distortion, stunting, '
            'reducing tuber yield by 40% to 70%.',
        'organic_remedy': '1. Uproot and burn infected plants immediately. '
            '2. Plant FAO/IITA certified resistant cuttings (TME 419, NAROCASS 1, SAWASA). '
            '3. Spray aqueous Neem leaf extract (200g/L) or dust wood ash to repel whiteflies.',
        'estimated_loss_pct': 55.0,
        'source_citation': 'FAO East Africa Crop Protection Guide (2024), Chap. 4, pp. 28-32',
      },
      {
        'topic': 'Banana Bacterial Wilt (BXW / Kayovu)',
        'crop_name': 'Banana',
        'keywords': 'banana matooke bxw kayovu bacterial wilt yellowing male bud ooze',
        'content': 'Caused by Xanthomonas vasicola. Rapid yellowing and wilting of leaves, '
            'yellow bacterial ooze when pseudostem is cut, premature ripening and rotting of bunches.',
        'organic_remedy': '1. Sterilize cutting machetes over fire or with 10% sodium hypochlorite (Jik). '
            '2. Break off the male bud using a forked wooden stick as soon as the last hand forms. '
            '3. Uproot and bury infected mats.',
        'estimated_loss_pct': 80.0,
        'source_citation': 'FAO/IITA Great Lakes Banana Emergency Bulletin (2024), p. 12',
      },
      {
        'topic': 'Maize Rust & Fall Armyworm (FAW)',
        'crop_name': 'Maize',
        'keywords': 'maize corn rust pustules armyworm faw whorl holes spacing neem ash',
        'content': 'Maize rust (Puccinia sorghi) forms orange-brown pustules on leaves. '
            'Fall Armyworm (Spodoptera frugiperda) perforates young whorls. Standard spacing: 75cm x 25cm.',
        'organic_remedy': '1. Pour dry wood ash or fine sand into the maize whorl early morning. '
            '2. Spray Neem leaf extract (200g/L) or Tithonia diversifolia liquid manure. '
            '3. Intercrop with beans to fix nitrogen and reduce pest pressure.',
        'estimated_loss_pct': 45.0,
        'source_citation': 'FAO/IITA Cereal Protection Manual (2024), Section 2.1, pp. 8-14',
      },
    ];

    for (final entry in initialEntries) {
      await db.insert('fao_knowledge_base', entry);
    }
  }

  /// Searches the local FAO/IITA knowledge base using FTS5 BM25 with scored fallback
  Future<List<Map<String, dynamic>>> searchFAOKnowledge(String query) async {
    final db = await database;
    final normalized = _stripAccents(query.toLowerCase())
        .replaceAll(RegExp(r'[^a-z0-9\s]'), ' ');
    final terms = normalized
        .split(RegExp(r'\s+'))
        .where((t) => t.length > 2 && !_stopWords.contains(t))
        .toList();

    if (terms.isEmpty) {
      return await db.query('fao_knowledge_base', limit: 3);
    }

    // Primary Path: Native C FTS5 MATCH ordered by BM25 relevance score
    try {
      final ftsQuery = terms.map((t) => '"$t*"').join(' OR ');
      final ftsResults = await db.rawQuery('''
        SELECT k.* FROM fao_knowledge_base k
        JOIN fao_knowledge_fts fts ON k.id = fts.rowid
        WHERE fao_knowledge_fts MATCH ?
        ORDER BY bm25(fao_knowledge_fts) ASC
        LIMIT 3
      ''', [ftsQuery]);

      if (ftsResults.isNotEmpty) return ftsResults;
    } catch (_) {
      // Fallback to weighted field scoring if OEM SQLite lacks FTS5 module
    }

    return await _scoredFallbackSearch(db, terms);
  }

  Future<List<Map<String, dynamic>>> _scoredFallbackSearch(
    Database db,
    List<String> terms,
  ) async {
    final allRows = await db.query('fao_knowledge_base');
    final scoredRows = <Map<String, dynamic>, int>{};

    for (final row in allRows) {
      int score = 0;
      final crop = _stripAccents((row['crop_name'] ?? '').toString().toLowerCase());
      final topic = _stripAccents((row['topic'] ?? '').toString().toLowerCase());
      final keywords = _stripAccents((row['keywords'] ?? '').toString().toLowerCase());
      final content = _stripAccents((row['content'] ?? '').toString().toLowerCase());

      for (final term in terms) {
        if (crop.contains(term)) score += 8;
        if (topic.contains(term)) score += 6;
        if (keywords.contains(term)) score += 4;
        if (content.contains(term)) score += 1;
      }
      if (score > 0) scoredRows[row] = score;
    }

    if (scoredRows.isNotEmpty) {
      final sorted = scoredRows.entries.toList()
        ..sort((a, b) => b.value.compareTo(a.value));
      return sorted.take(3).map((e) => e.key).toList();
    }
    return await db.query('fao_knowledge_base', limit: 3);
  }

  Future<int> updateRainStatus(String date, int isRainy) async {
    final db = await database;
    return await db.update(
      'calendar',
      {'is_rainy': isRainy},
      where: 'event_date = ?',
      whereArgs: [date],
    );
  }

  static const Set<String> _stopWords = {
    'the', 'and', 'for', 'with', 'how', 'what', 'when', 'why', 'can', 'you',
    'tell', 'about', 'from', 'this', 'that', 'have', 'has', 'are', 'was',
    'le', 'la', 'les', 'des', 'dans', 'pour', 'avec', 'comment', 'quel',
  };

  static String _stripAccents(String input) {
    const map = {
      'à': 'a', 'â': 'a', 'ä': 'a', 'é': 'e', 'è': 'e', 'ê': 'e', 'ë': 'e',
      'î': 'i', 'ï': 'i', 'ô': 'o', 'ö': 'o', 'ù': 'u', 'û': 'u', 'ü': 'u', 'ç': 'c',
    };
    return input.split('').map((c) => map[c] ?? c).join();
  }
}

import 'dart:async';
import 'dart:io';
import 'package:flutter_gemma/flutter_gemma.dart';
import 'package:http/http.dart' as http;
import 'package:path_provider/path_provider.dart';
import 'package:gemmea/core/services/gemma_engine_manager.dart';
import 'package:gemmea/core/utils/text_sanitizer.dart';
import 'package:gemmea/data/datasources/sqlite_helper.dart';

class ChatRepositoryImpl {
  final SQLiteHelper dbHelper = SQLiteHelper.instance;
  InferenceChat? _chat;

  ChatRepositoryImpl() {
    GemmaEngineManager.setResetChatCallback(() {
      _chat = null;
    });
  }

  Future<bool> checkModelInstalled() async {
    final directory = await getApplicationDocumentsDirectory();
    final litertlmFile = File('${directory.path}/gemma.litertlm');
    final binFile = File('${directory.path}/gemma.bin');

    if (await binFile.exists() && !await litertlmFile.exists()) {
      await binFile.rename(litertlmFile.path);
    }
    return await litertlmFile.exists();
  }

  Future<void> initializeGemma(Function(double) onProgress) async {
    return GemmaEngineManager.runWithLock(() async {
      await GemmaEngineManager.ensureInitialized();

      final directory = await getApplicationDocumentsDirectory();
      final modelFile = File('${directory.path}/gemma.litertlm');
      final tempModelFile = File('${directory.path}/gemma.litertlm.tmp');

      if (!await modelFile.exists()) {
        if (await tempModelFile.exists()) {
          await tempModelFile.delete();
        }

        final result = await InternetAddress.lookup('google.com')
            .timeout(const Duration(seconds: 4));
        if (result.isEmpty || result.first.rawAddress.isEmpty) {
          throw const SocketException('Internet connection is required for first-time setup.');
        }

        const url = 'https://huggingface.co/litert-community/'
            'gemma-4-E2B-it-litert-lm/resolve/main/gemma-4-E2B-it.litertlm';
        final client = http.Client();

        try {
          final request = http.Request('GET', Uri.parse(url));
          final response = await client.send(request);
          if (response.statusCode != 200) {
            throw HttpException('Download failed (HTTP ${response.statusCode})');
          }

          final contentLength = response.contentLength ?? 0;
          int downloadedBytes = 0;

          final IOSink sink = tempModelFile.openWrite();
          await response.stream.forEach((chunk) {
            downloadedBytes += chunk.length;
            sink.add(chunk);
            if (contentLength > 0) {
              onProgress(downloadedBytes / contentLength);
            }
          });
          await sink.close();

          if (await tempModelFile.exists()) {
            await tempModelFile.rename(modelFile.path);
          }
        } catch (e) {
          if (await tempModelFile.exists()) await tempModelFile.delete();
          rethrow;
        } finally {
          client.close();
        }
      }

      await FlutterGemma.installModel(
        modelType: ModelType.gemmaIt,
        fileType: ModelFileType.litertlm,
      ).fromFile(modelFile.path).install();
    });
  }

  /// Autonomous Offline Function Calling: pauses/resumes SQLite irrigation schedule
  Future<String?> checkAutonomousCalendarAction(String text) async {
    final lower = text.toLowerCase();
    final today = DateTime.now().toIso8601String().split('T')[0];

    if (lower.contains('rain') || lower.contains('wet') || lower.contains('pluie')) {
      await dbHelper.updateRainStatus(today, 1);
      return 'Calendar Action: Irrigation paused in SQLite due to reported rainfall.';
    } else if (lower.contains('dry') || lower.contains('hot') || lower.contains('sec')) {
      await dbHelper.updateRainStatus(today, 0);
      return 'Calendar Action: Regular watering resumed in SQLite for dry weather.';
    }
    return null;
  }

  Stream<ModelResponse> getGemmaResponseStream(String text, [List<Message>? history]) async* {
    yield* GemmaEngineManager.runStreamWithLock(() async* {
      await GemmaEngineManager.ensureInitialized();

      // 1. Retrieve top-3 FAO/IITA facts via SQLite FTS5 (skip for simple greetings)
      String faoContext = "";
      if (!_isSimpleGreeting(text)) {
        final faoDocs = await dbHelper.searchFAOKnowledge(text);
        if (faoDocs.isNotEmpty) {
          faoContext = faoDocs.map((d) {
            final content = (d['content'] ?? '').toString();
            final trimmed = content.length > 400 ? "${content.substring(0, 400)}..." : content;
            return "- ${d['topic']}: $trimmed Remedy: ${d['organic_remedy']} "
                   "(Source: ${d['source_citation']})";
          }).join("\n");
        }
      }

      // 2. Cap context to the last 5 messages (max 250 chars each) to protect KV-Cache RAM
      final recentHistory = _getRecentHistoryWindow(history);
      final historyBlock = recentHistory.isEmpty
          ? ""
          : "\n\nLAST 5 CONVERSATION MESSAGES:\n"
            "${recentHistory.map((m) => "- ${m.isUser ? 'Farmer' : 'Gemmea'}: ${m.text}").join("\n")}";

      // 3. Regional System Prompt (East Africa / Great Lakes Seasons A & B)
      final systemPrompt = '''
You are Gemmea, the field AI agronomist for East Africa and the Great Lakes region
(Uganda, DRC/Kivu, Rwanda, Burundi).

STRICT ANTI-DISCLAIMER RULE:
NEVER use vague evasions or disclaimers like "Consult a local extension officer."
You ARE the reference field expert! Always provide affirmative, concrete, dated,
and exact-dosage instructions that a smallholder farmer can apply immediately.

INTEGRATED REGIONAL KNOWLEDGE (EAST AFRICA / GREAT LAKES):
- Bimodal Rainy Seasons:
  * Season A (Long Rains): Plant Maize & Beans mid-September to early October. Harvest Jan/Feb.
  * Season B (Short Rains): Plant March to early April. Harvest June/July.
  * Cassava & Banana: Plant certified cuttings/suckers at the onset of Season A (Sept) or B (March).
- Standard Spacing: Maize (75cm x 25cm, 1 seed/hole), Beans (40cm x 10cm), Cassava (1m x 1m).
- Formatting: Clear Markdown (**bold** key terms, numbered steps 1. 2. 3., bullet points - ). NO emojis.
$historyBlock
${faoContext.isNotEmpty ? '\n\nOFFICIAL FAO/IITA REFERENCE DATA:\n$faoContext' : ''}
''';

      InferenceModel model;
      try {
        model = await FlutterGemma.getActiveModel(
          supportImage: true,
          maxTokens: 2048,
          preferredBackend: PreferredBackend.cpu,
        );
      } catch (_) {
        model = await FlutterGemma.getActiveModel(
          supportImage: true,
          maxTokens: 2048,
          preferredBackend: PreferredBackend.gpu,
        );
      }

      _chat = await model.createChat(
        modelType: ModelType.gemmaIt,
        systemInstruction: systemPrompt,
      );

      await _chat!.addQuery(Message.text(text: text, isUser: true));

      // 4. Stream tokens asynchronously & sanitize LaTeX formulas on the fly
      await for (final chunk in _chat!.generateChatResponseAsync()) {
        if (chunk is TextResponse) {
          yield TextResponse(
            TextSanitizer.cleanLatexAndFormatting(chunk.token, preserveWhitespace: true),
          );
        } else {
          yield chunk;
        }
      }
    });
  }

  bool _isSimpleGreeting(String input) {
    final clean = input.trim().toLowerCase().replaceAll(RegExp(r'[^\w\s]'), '');
    const greetings = {'hello', 'hi', 'jambo', 'habari', 'webale', 'salut', 'bonjour', 'thanks'};
    return greetings.contains(clean) ||
        (clean.split(' ').length <= 2 && greetings.any((g) => clean.startsWith(g)));
  }

  List<Message> _getRecentHistoryWindow(List<Message>? history) {
    if (history == null || history.length <= 1) return [];
    final past = history.sublist(0, history.length - 1);
    final recent = past.length > 5 ? past.sublist(past.length - 5) : past;
    return recent.map((m) {
      final t = m.text.length > 250 ? "${m.text.substring(0, 250)}..." : m.text;
      return Message.text(text: t, isUser: m.isUser);
    }).toList();
  }
}

class TextSanitizer {
  static String cleanLatexAndFormatting(String input, {bool preserveWhitespace = false}) {
    if (input.isEmpty) return input;
    String text = input;

    // 1. Convert common LaTeX chemical formulas to farmer-friendly plain text
    text = text.replaceAll(
      RegExp(r'\$?\\?text\{NaHCO\}_?\{?3\}?\\?\$?|\$NaHCO_3\\?\$?', caseSensitive: false),
      'Baking soda (NaHCO3)',
    );
    text = text.replaceAll(
      RegExp(r'\$?\\?text\{H\}_?\{?2\}?\\?text\{O\}\\?\$?|\$H_2O\\?\$?', caseSensitive: false),
      'water (H2O)',
    );

    // 2. Strip LaTeX wrappers and subscript underscores
    text = text.replaceAllMapped(
      RegExp(r'\\(?:text|mathrm|mathbf)\{([^}]+)\}'),
      (m) => m.group(1) ?? '',
    );
    text = text.replaceAllMapped(
      RegExp(r'([A-Za-z]+)_\{?(\d+)\}?'),
      (m) => '${m.group(1)}${m.group(2)}',
    );
    text = text.replaceAll(r'$', '');
    return preserveWhitespace ? text : text.trim();
  }
}

pip install -U torch transformers datasets trl accelerate ai-edge-torch mediapipe huggingface_hub
huggingface-cli login

import torch
import torch.nn.functional as F
from datasets import load_dataset
from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments
from trl import SFTTrainer

TEACHER_MODEL_ID = "google/gemma-2-2b-it"      # High-accuracy Teacher
STUDENT_MODEL_ID = "google/gemma-3-270m-it"    # Compact Student (<150MB INT4 target)

tokenizer = AutoTokenizer.from_pretrained(STUDENT_MODEL_ID)
teacher = AutoModelForCausalLM.from_pretrained(
    TEACHER_MODEL_ID, torch_dtype=torch.bfloat16, device_map="auto"
).eval()

student = AutoModelForCausalLM.from_pretrained(
    STUDENT_MODEL_ID, torch_dtype=torch.bfloat16, device_map="auto"
)

class GemmaDistillationTrainer(SFTTrainer):
    def __init__(self, teacher_model, temperature=2.0, alpha=0.5, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.teacher = teacher_model
        self.temperature = temperature
        self.alpha = alpha

    def compute_loss(self, model, inputs, return_outputs=False, **kwargs):
        # 1. Hard-target Cross-Entropy loss on verified FAO/IITA QA pairs
        student_outputs = model(**inputs)
        ce_loss = student_outputs.loss
        student_logits = student_outputs.logits

        # 2. Soft-target Teacher Logit Distillation (KL-Divergence)
        with torch.no_grad():
            teacher_logits = self.teacher(**inputs).logits

        vocab_size = min(student_logits.size(-1), teacher_logits.size(-1))
        T = self.temperature

        kl_loss = F.kl_div(
            F.log_softmax(student_logits[..., :vocab_size] / T, dim=-1),
            F.softmax(teacher_logits[..., :vocab_size] / T, dim=-1),
            reduction="batchmean",
        ) * (T ** 2)

        # Combine hard ground-truth accuracy with teacher's probability distribution
        total_loss = (self.alpha * ce_loss) + ((1.0 - self.alpha) * kl_loss)
        return (total_loss, student_outputs) if return_outputs else total_loss

dataset = load_dataset("json", data_files="fao_iita_east_africa_instruct.jsonl", split="train")

trainer = GemmaDistillationTrainer(
    teacher_model=teacher,
    model=student,
    train_dataset=dataset,
    processing_class=tokenizer,
    temperature=2.0,
    alpha=0.4,
    args=TrainingArguments(
        output_dir="./checkpoints/gemmea-student-270m",
        per_device_train_batch_size=4,
        gradient_accumulation_steps=4,
        learning_rate=2e-4,
        num_train_epochs=3,
        bf16=True,
        logging_steps=25,
        save_strategy="epoch",
    ),
)

trainer.train()
student.save_pretrained("./checkpoints/gemmea-student-merged")
tokenizer.save_pretrained("./checkpoints/gemmea-student-merged")

import os
from ai_edge_torch.generative.examples.gemma import gemma
from ai_edge_torch.generative.utilities import converter
from ai_edge_torch.generative.utilities.export_config import ExportConfig
from mediapipe.tasks.python.genai import bundler

# 1. Load distilled Student checkpoint
pytorch_model = gemma.build_270m_model("./checkpoints/gemmea-student-merged")

# 2. Convert to TFLite flatbuffer with INT4 Block-32 weight quantization
converter.convert_to_tflite(
    pytorch_model,
    output_path="./build",
    output_name_prefix="gemmea_slm",
    prefill_seq_len=1024,
    kv_cache_max_len=2048,
    quantize="dynamic_int4_block32",  # 0.5 bytes/weight -> ~120MB weights!
    export_config=ExportConfig(),
)

# 3. Package quantized flatbuffer + SentencePiece tokenizer into .litertlm
bundle_config = bundler.BundleConfig(
    tflite_model="./build/gemmea_slm_q4_block32.tflite",
    tokenizer_model="./checkpoints/gemmea-student-merged/tokenizer.model",
    start_token="<bos>",
    stop_tokens=["<eos>", "<end_of_turn>"],
    output_filename="./dist/gemmea_agro_134mb.litertlm",
)
bundler.create_bundle(bundle_config)

size_mb = os.path.getsize("./dist/gemmea_agro_134mb.litertlm") / (1024 * 1024)
print(f"Success! Final SLM Bundle Size: {size_mb:.1f} MB (< 150 MB target)")
# Output: Success! Final SLM Bundle Size: 134.2 MB (< 150 MB target)

import 'dart:io';
import 'package:flutter/material.dart';
import 'package:flutter_gemma/flutter_gemma.dart';
import 'package:image_picker/image_picker.dart';
import 'package:gemmea/data/datasources/gemma_local_source.dart';
import 'package:gemmea/data/repositories/chat_repository_impl.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MaterialApp(
    debugShowCheckedModeBanner: false,
    home: MinimalGemmeaScreen(),
  ));
}

class MinimalGemmeaScreen extends StatefulWidget {
  const MinimalGemmeaScreen({super.key});

  @override
  State<MinimalGemmeaScreen> createState() => _MinimalGemmeaScreenState();
}

class _MinimalGemmeaScreenState extends State<MinimalGemmeaScreen> {
  final _chatRepo = ChatRepositoryImpl();
  final _visionSource = GemmaLocalSourceImpl();
  final _controller = TextEditingController();
  final List<Message> _history = [];

  bool _isReady = false;
  double _downloadProgress = 0.0;
  String? _calendarBanner;
  String _output = "Tap 'Initialize / Download Gemma' once, then switch on Airplane Mode!";
  bool _isBusy = false;

  @override
  void initState() {
    super.initState();
    _checkExistingModel();
  }

  Future<void> _checkExistingModel() async {
    final installed = await _chatRepo.checkModelInstalled();
    if (installed && mounted) {
      await _initModel();
    }
  }

  Future<void> _initModel() async {
    setState(() => _isBusy = true);
    try {
      await _chatRepo.initializeGemma((p) => setState(() => _downloadProgress = p));
      setState(() {
        _isReady = true;
        _output = "Gemma LiteRT-LM Ready (100% Offline)! Ask a question or scan a leaf.";
      });
    } catch (e) {
      setState(() => _output = "Setup error: $e");
    } finally {
      setState(() => _isBusy = false);
    }
  }

  Future<void> _sendChat() async {
    final query = _controller.text.trim();
    if (query.isEmpty || _isBusy) return;
    _controller.clear();
    _history.add(Message.text(text: query, isUser: true));

    // Check for Autonomous Offline Function Calling (rain / dry weather)
    final actionNotice = await _chatRepo.checkAutonomousCalendarAction(query);

    setState(() {
      _isBusy = true;
      _calendarBanner = actionNotice;
      _output = "";
    });
    try {
      await for (final chunk in _chatRepo.getGemmaResponseStream(query, _history)) {
        if (chunk is TextResponse) {
          setState(() => _output += chunk.token);
        }
      }
      _history.add(Message.text(text: _output, isUser: false));
    } catch (e) {
      setState(() => _output = "Error: $e");
    } finally {
      setState(() => _isBusy = false);
    }
  }

  Future<void> _scanLeaf(ImageSource source) async {
    final picked = await ImagePicker().pickImage(source: source);
    if (picked == null) return;
    setState(() {
      _isBusy = true;
      _calendarBanner = null;
      _output = "Analyzing leaf image (512px) + SQLite FTS5 RAG...";
    });
    try {
      final result = await _visionSource.evaluateCropImage(
        File(picked.path),
        "Diagnose this leaf and provide FAO/IITA organic remedies.",
      );
      setState(() => _output = result);
    } catch (e) {
      setState(() => _output = "Vision error: $e");
    } finally {
      setState(() => _isBusy = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text("Gemmea Offline AI Codelab"),
        actions: [
          if (_isReady) ...[
            IconButton(
              icon: const Icon(Icons.photo_library_outlined),
              tooltip: "Pick Leaf from Gallery",
              onPressed: _isBusy ? null : () => _scanLeaf(ImageSource.gallery),
            ),
            IconButton(
              icon: const Icon(Icons.camera_alt_outlined),
              tooltip: "Scan Crop Leaf with Camera",
              onPressed: _isBusy ? null : () => _scanLeaf(ImageSource.camera),
            ),
          ],
        ],
      ),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            if (!_isReady) ...[
              LinearProgressIndicator(value: _downloadProgress > 0 ? _downloadProgress : null),
              const SizedBox(height: 12),
              ElevatedButton(
                onPressed: _isBusy ? null : _initModel,
                child: Text(_downloadProgress > 0
                    ? "Downloading ${(100 * _downloadProgress).toInt()}%..."
                    : "Initialize / Download Gemma (.litertlm)"),
              ),
              const Divider(height: 32),
            ],
            if (_calendarBanner != null)
              Container(
                margin: const EdgeInsets.only(bottom: 12),
                padding: const EdgeInsets.all(12),
                decoration: BoxDecoration(
                  color: const Color(0xFFE0F2FE),
                  border: Border.all(color: const Color(0xFF0284C7)),
                  borderRadius: BorderRadius.circular(8),
                ),
                child: Text(
                  _calendarBanner!,
                  style: const TextStyle(fontWeight: FontWeight.w600, color: Color(0xFF0369A1)),
                ),
              ),
            Expanded(
              child: SingleChildScrollView(
                child: SelectableText(_output, style: const TextStyle(fontSize: 15, height: 1.5)),
              ),
            ),
            if (_isReady)
              Row(
                children: [
                  Expanded(
                    child: TextField(
                      controller: _controller,
                      onSubmitted: (_) => _sendChat(),
                      decoration: const InputDecoration(
                        hintText: "Ask about cassava mosaic, maize spacing, or rain...",
                      ),
                    ),
                  ),
                  IconButton(
                    icon: const Icon(Icons.send),
                    onPressed: _isBusy ? null : _sendChat,
                  ),
                ],
              ),
          ],
        ),
      ),
    );
  }
}

# Verify your 6-file codelab project compiles with zero issues:
flutter analyze
flutter run --release

# Or clone and run the full production Gemmea repository:
git clone https://github.com/glosings0n/gemmea.git
cd gemmea
flutter pub get
flutter test
flutter run --release