kyc_engine 0.0.2

A Flutter library for face verification and KYC processes.

KYC Engine 🔐

A Flutter package for face verification using TensorFlow Lite and Firebase ML. Compare two face images to verify if they're the same person.

Features

• 🎯 Face verification with similarity scoring
• 🔒 Privacy-first - all processing on-device
• 🚀 Pre-trained model included
• ⚡ Fast mobile performance
• 📱 iOS and Android support

Installation

dependencies:
  kyc_engine: ^0.0.1
  firebase_core: ^4.2.1

Setup

1. Configure Firebase

dart pub global activate flutterfire_cli
flutterfire configure

2. iOS Setup

Update ios/Podfile:

platform :ios, '15.5'

That's it! The pre-trained model (~27.5 MB) will download automatically from Firebase on first use.

Usage

import 'package:kyc_engine/kyc_engine.dart';
import 'dart:io';

// Initialize
final kycEngine = KYCEngine();
await kycEngine.initialize();

// Compare faces
final result = await kycEngine.verifyFaces(
  File('image1.jpg'),
  File('image2.jpg'),
);

// Check result
if (result.isSamePerson) {
  print('✅ Match! ${result.confidencePercentage.toStringAsFixed(1)}% confidence');
} else {
  print('❌ No match');
}

API

Methods

// Initialize engine (call first)
await kycEngine.initialize();

// Compare two faces - returns detailed result
final result = await kycEngine.verifyFaces(image1, image2);

// Quick boolean check
final match = await kycEngine.areSimilar(image1, image2);

// Get raw similarity score (0.0 - 1.0)
final score = await kycEngine.getSimilarityScore(image1, image2);

Configuration Presets

await kycEngine.initialize(FaceDetectionConfig.accurate()); // Default, balanced
await kycEngine.initialize(FaceDetectionConfig.fast());     // Speed optimized
await kycEngine.initialize(FaceDetectionConfig.strict());   // High security (0.7 threshold)
await kycEngine.initialize(FaceDetectionConfig.lenient());  // Fewer false negatives (0.5)

Custom Configuration

await kycEngine.initialize(
  FaceDetectionConfig(
    similarityThreshold: 0.65,
    performanceMode: FaceDetectorMode.accurate,
    enableLandmarks: true,
  ),
);

Understanding Results

Thresholds

Threshold	Use Case
0.7 - 0.8	Banking, government ID
0.6 - 0.7	Standard KYC (default)
0.5 - 0.6	Social apps
0.4 - 0.5	Duplicate detection

Score Interpretation

• 0.8 - 1.0: Very high confidence
• 0.6 - 0.8: High confidence (typical matches)
• 0.4 - 0.6: Uncertain
• 0.0 - 0.4: Different persons

Error Handling

try {
  final result = await kycEngine.verifyFaces(image1, image2);
} on ServiceNotInitializedException {
  print('Call initialize() first');
} on NoFaceDetectedException {
  print('No face detected in image');
} on InvalidImageException {
  print('Invalid image file');
} on ModelInitializationException {
  print('Model download failed - check internet connection');
} on KYCException catch (e) {
  print('Error: ${e.message}');
}

How It Works

1. Detects faces using Google ML Kit
2. Extracts face region
3. Generates embedding (128-d vector) with TFLite
4. Normalizes embeddings (L2)
5. Calculates cosine similarity
6. Compares against threshold

Notes:

• Only the first detected face is used
• Image orientation auto-corrected
• All processing on-device

Requirements

• Flutter ≥ 3.0.0
• iOS ≥ 15.5 / Android ≥ 24
• Firebase project
• Internet for initial download

Tips

• Use clear, well-lit images
• Face should be visible and unobstructed
• Recommended: 512x512 to 1024x1024 pixels
• Start with default threshold (0.6), adjust based on testing
• Call dispose() when done

Advanced: Custom Model

To use your own face recognition model:

await kycEngine.initialize(
  FaceDetectionConfig(
    firebaseModelName: 'your_model_name',
  ),
);

Upload your model to Firebase Console → ML → Custom Models.

License

MIT License - see LICENSE file.

Support

• 📧 Email: [e-mail]
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

---

Built with ❤️ by Eric Atsu

If this helps you, give it a ⭐ on GitHub!