DEV Community: David Au Yeung

Build a Facial Recognition System with C#, ArcFace ONNX, and OpenCV DNN

David Au Yeung — Wed, 17 Jun 2026 07:55:17 +0000

Introduction

Ever wondered how to build a real facial recognition system in C#? The kind that can actually tell different people apart, not just compare entire images? Today, we're going to build exactly that-a production-ready facial recognition demo that uses state-of-the-art deep learning models.

By the end of this tutorial, you'll have a working application that can:

Detect faces in images automatically
Generate unique "fingerprints" (embeddings) for each face
Compare faces with high accuracy
Tell you if two photos are of the same person

What makes this special? We're combining two powerful technologies:

OpenCV DNN Face Detector - Finds and crops faces automatically
ArcFace ONNX Model - Generates 512-dimensional face embeddings

No cloud APIs, no subscription fees-everything runs locally on your machine.

Prerequisites
Understanding the Technology
Setting Up the Project
Downloading the Models
Building the Face Recognition Service
Creating the Main Application
How It All Works Together
Testing Your System
The Journey to Better Accuracy
Next Steps

Prerequisites

Before we dive in, make sure you have:

.NET 8 SDK installed
Visual Studio 2022 or Visual Studio Code
Basic C# knowledge
A few test images of people (we'll need at least 3-4 photos)

That's it! Everything else we'll install as we go.

Understanding the Technology

Why Two Models?

You might be wondering: "Why do we need two models?" Great question! Let me explain with a real-world analogy.

Imagine you're a detective trying to match a suspect's photo:

First, you need to find the face in a crowded photo (maybe there's a background, other people, etc.)
Then, you need to analyze just the face to identify the person

That's exactly what our two models do:

1. OpenCV DNN Face Detector (The "Face Finder")

Job: Find faces in images
Input: Any image (any size)
Output: Bounding boxes around detected faces
Model: Caffe-based SSD (Single Shot Detector)
Speed: Very fast (~20-30ms per image)

2. ArcFace ONNX (The "Face Recognizer")

Job: Convert face images into unique numerical signatures
Input: 112x112 RGB face image
Output: 512-dimensional vector (called an "embedding")
Magic: Faces of the same person produce similar vectors!
Speed: Fast (~10-15ms per face)

What is ArcFace?

ArcFace is a state-of-the-art face recognition model developed by researchers. Here's why it's amazing:

Accuracy: One of the most accurate face recognition models available
Embeddings: Converts faces into 512 numbers that capture facial features
Comparison: Same person = similar embeddings (cosine similarity > 0.6)
Different people: Different embeddings (cosine similarity < 0.5)

Think of embeddings as a "facial fingerprint"-unique to each person, but similar between photos of the same person.

The Face Recognition Pipeline

Here's the complete flow:

Input Image
    ↓
[OpenCV DNN: Find Face]
    ↓
Crop to Face Region (with margin)
    ↓
Resize to 112x112
    ↓
Normalize pixels to [-1, 1]
    ↓
[ArcFace: Generate Embedding]
    ↓
512 numbers representing the face
    ↓
[Compare with other embeddings]
    ↓
Similarity Score (0.0 to 1.0)
    ↓
Decision: Same person or different?

Now let's build it!

Setting Up the Project

Step 1: Create a New Console Application

Open your terminal and run:

dotnet new console -n FaceRecognitionDemo
cd FaceRecognitionDemo

Step 2: Install Required NuGet Packages

We need three packages:

dotnet add package Microsoft.ML.OnnxRuntime
dotnet add package OpenCvSharp4
dotnet add package OpenCvSharp4.runtime.win

What each package does:

Microsoft.ML.OnnxRuntime - Runs ONNX models (for ArcFace)
OpenCvSharp4 - Computer vision operations (image processing, face detection)
OpenCvSharp4.runtime.win - Native Windows binaries for OpenCV

Step 3: Create Project Folders

mkdir Photos
mkdir Models

Photos/ - Where you'll put test images
Models/ - Where we'll download our AI models

Downloading the Models

Model 1: ArcFace ONNX (Face Recognition)

Option A: Download via Browser

Go to: https://huggingface.co/garavv/arcface-onnx

Click on "Files and versions" → Download arc.onnx

Rename it to arcface.onnx and place it in the Models/ folder.

Option B: Download via Command Line (PowerShell)

# Navigate to your project directory
cd FaceRecognitionDemo

# Download the model
Invoke-WebRequest -Uri "https://huggingface.co/garavv/arcface-onnx/resolve/main/arc.onnx?download=true" `
    -OutFile "Models/arcface.onnx"

Or using curl:

curl -L "https://huggingface.co/garavv/arcface-onnx/resolve/main/arc.onnx?download=true" -o Models/arcface.onnx

File size: ~130MB (be patient, it's worth it!)

Model 2: OpenCV Face Detection Models

These are smaller and faster to download:

# Face detector configuration
Invoke-WebRequest -Uri "https://raw.githubusercontent.com/opencv/opencv/master/samples/dnn/face_detector/deploy.prototxt" `
    -OutFile "Models/deploy.prototxt"

# Face detector weights
Invoke-WebRequest -Uri "https://github.com/opencv/opencv_3rdparty/raw/dnn_samples_face_detector_20170830/res10_300x300_ssd_iter_140000.caffemodel" `
    -OutFile "Models/res10_300x300_ssd_iter_140000.caffemodel"

Your Models folder should now have:

✅ arcface.onnx (130 MB)
✅ deploy.prototxt (28 KB)
✅ res10_300x300_ssd_iter_140000.caffemodel (10 MB)

Building the Face Recognition Service

Now for the fun part-writing the code! Create a new file called ImprovedFaceRecognitionService.cs:

using Microsoft.ML.OnnxRuntime;
using Microsoft.ML.OnnxRuntime.Tensors;
using OpenCvSharp;
using OpenCvSharp.Dnn;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;

public class ImprovedFaceRecognitionService : IDisposable
{
    private readonly InferenceSession _session;
    private readonly string _inputName;
    private readonly Net? _faceDetector;
    private readonly bool _useFaceDetection;

    public ImprovedFaceRecognitionService(
        string modelPath, 
        string? faceDetectorProto = null, 
        string? faceDetectorModel = null)
    {
        // Load ArcFace ONNX model
        _session = new InferenceSession(modelPath);
        _inputName = _session.InputMetadata.Keys.First();

        // Initialize OpenCV face detector if models provided
        if (!string.IsNullOrEmpty(faceDetectorProto) && 
            !string.IsNullOrEmpty(faceDetectorModel) &&
            File.Exists(faceDetectorProto) && 
            File.Exists(faceDetectorModel))
        {
            _faceDetector = CvDnn.ReadNetFromCaffe(faceDetectorProto, faceDetectorModel);
            _useFaceDetection = true;
            Console.WriteLine("✓ Face detection enabled");
        }
        else
        {
            _useFaceDetection = false;
            Console.WriteLine("ℹ Face detection disabled - using full images");
        }
    }

    public FaceEmbeddingResult GetEmbedding(string imagePath)
    {
        // Validate file
        if (!File.Exists(imagePath))
        {
            throw new FileNotFoundException($"Image file not found: {imagePath}");
        }

        if (imagePath.Length > 250)
        {
            throw new ArgumentException($"File path is too long ({imagePath.Length} characters).");
        }

        // Load image
        using Mat image = Cv2.ImRead(imagePath, ImreadModes.Color);
        if (image.Empty())
        {
            return new FaceEmbeddingResult
            {
                Success = false,
                ErrorMessage = $"Could not read image: {Path.GetFileName(imagePath)}"
            };
        }

        // Detect and crop face if face detection is enabled
        Mat faceImage;
        if (_useFaceDetection && _faceDetector != null)
        {
            var faceRect = DetectLargestFace(image);
            if (faceRect == null)
            {
                return new FaceEmbeddingResult
                {
                    Success = false,
                    ErrorMessage = "No face detected in image"
                };
            }

            // Crop to face with 20% margin
            var rect = faceRect.Value;
            int margin = (int)(Math.Max(rect.Width, rect.Height) * 0.2);
            int x = Math.Max(0, rect.X - margin);
            int y = Math.Max(0, rect.Y - margin);
            int width = Math.Min(image.Width - x, rect.Width + 2 * margin);
            int height = Math.Min(image.Height - y, rect.Height + 2 * margin);

            faceImage = new Mat(image, new Rect(x, y, width, height));
        }
        else
        {
            faceImage = image;
        }

        // Process face for ArcFace
        var embedding = ProcessFaceForArcFace(faceImage);

        return new FaceEmbeddingResult
        {
            Success = true,
            Embedding = embedding,
            FaceDetected = _useFaceDetection
        };
    }

    private Rect? DetectLargestFace(Mat image)
    {
        if (_faceDetector == null) return null;

        // Prepare image blob for detection
        using var blob = CvDnn.BlobFromImage(
            image, 
            1.0, 
            new Size(300, 300), 
            new Scalar(104, 177, 123), 
            false, 
            false
        );

        _faceDetector.SetInput(blob);
        using var detection = _faceDetector.Forward();

        // Find face with highest confidence
        Rect? bestFace = null;
        float bestConfidence = 0;

        int rows = detection.Size(2);
        for (int i = 0; i < rows; i++)
        {
            float confidence = detection.At<float>(0, 0, i, 2);

            if (confidence > 0.5) // 50% confidence threshold
            {
                int x1 = (int)(detection.At<float>(0, 0, i, 3) * image.Width);
                int y1 = (int)(detection.At<float>(0, 0, i, 4) * image.Height);
                int x2 = (int)(detection.At<float>(0, 0, i, 5) * image.Width);
                int y2 = (int)(detection.At<float>(0, 0, i, 6) * image.Height);

                if (confidence > bestConfidence)
                {
                    bestConfidence = confidence;
                    bestFace = new Rect(x1, y1, x2 - x1, y2 - y1);
                }
            }
        }

        return bestFace;
    }

    private float[] ProcessFaceForArcFace(Mat faceImage)
    {
        // Step 1: Resize to 112x112 (ArcFace requirement)
        using Mat resizedImage = new Mat();
        Cv2.Resize(faceImage, resizedImage, new Size(112, 112));

        // Step 2: Convert BGR to RGB
        using Mat rgbImage = new Mat();
        Cv2.CvtColor(resizedImage, rgbImage, ColorConversionCodes.BGR2RGB);

        // Step 3: Normalize to [-1, 1]
        using Mat floatImage = new Mat();
        rgbImage.ConvertTo(floatImage, MatType.CV_32FC3, 1.0 / 128.0, -127.5 / 128.0);

        // Step 4: Create ONNX tensor (NHWC format)
        var inputTensor = new DenseTensor<float>(new[] { 1, 112, 112, 3 });

        for (int y = 0; y < 112; y++)
        {
            for (int x = 0; x < 112; x++)
            {
                Vec3f pixel = floatImage.At<Vec3f>(y, x);
                inputTensor[0, y, x, 0] = pixel.Item0;
                inputTensor[0, y, x, 1] = pixel.Item1;
                inputTensor[0, y, x, 2] = pixel.Item2;
            }
        }

        // Step 5: Run inference
        var inputs = new List<NamedOnnxValue>
        {
            NamedOnnxValue.CreateFromTensor(_inputName, inputTensor)
        };

        using IDisposableReadOnlyCollection<DisposableNamedOnnxValue> results = 
            _session.Run(inputs);
        var output = results.First().AsEnumerable<float>().ToArray();

        // Step 6: Normalize embedding to unit vector
        return Normalize(output);
    }

    public static float CosineSimilarity(float[] a, float[] b)
    {
        float dot = 0;
        for (int i = 0; i < a.Length; i++)
        {
            dot += a[i] * b[i];
        }
        // Since vectors are normalized, dot product = cosine similarity
        return dot;
    }

    private float[] Normalize(float[] v)
    {
        float norm = (float)Math.Sqrt(v.Sum(x => x * x));
        if (norm == 0) return v;
        return v.Select(x => x / norm).ToArray();
    }

    public void Dispose()
    {
        _session?.Dispose();
        _faceDetector?.Dispose();
    }
}

public class FaceEmbeddingResult
{
    public bool Success { get; set; }
    public float[]? Embedding { get; set; }
    public bool FaceDetected { get; set; }
    public string? ErrorMessage { get; set; }
}

Understanding the Code

Let's break down what each part does:

Constructor

Loads the ArcFace ONNX model
Optionally loads OpenCV face detector
Tells you if face detection is enabled

`GetEmbedding()` Method

Validates the image file exists
Loads the image with OpenCV
If face detection enabled → finds and crops the face
Processes the face for ArcFace
Returns embedding or error message

`DetectLargestFace()` Method

Uses OpenCV DNN to find faces
Returns the face with highest confidence
Confidence threshold: 50%

`ProcessFaceForArcFace()` Method

This is where the magic happens:

Resize → 112x112 pixels
Color Convert → BGR to RGB
Normalize → Pixel values to [-1, 1]
Tensorize → Convert to ONNX tensor
Inference → Run through ArcFace model
Normalize → Unit vector for comparison

`CosineSimilarity()` Method

Compares two embeddings
Returns value from 0.0 (completely different) to 1.0 (identical)
Same person typically scores > 0.6

Creating the Main Application

Now let's build the main program. Replace your Program.cs:

using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Text;

internal static class Program
{
    public static void Main(string[] args)
    {
        Console.OutputEncoding = Encoding.UTF8;
        Console.WriteLine("Starting Improved Facial Recognition Demo...");
        Console.WriteLine("Using ArcFace ONNX + OpenCV DNN Face Detection\n");

        string projectRoot = GetProjectRootDirectory();
        string photosPath = Path.Combine(projectRoot, "Photos");
        string modelsPath = Path.Combine(projectRoot, "Models");
        string arcfaceModel = Path.Combine(modelsPath, "arcface.onnx");
        string faceDetectorProto = Path.Combine(modelsPath, "deploy.prototxt");
        string faceDetectorModel = Path.Combine(modelsPath, "res10_300x300_ssd_iter_140000.caffemodel");

        // Validate directories
        if (!Directory.Exists(photosPath))
        {
            Console.WriteLine($"The Photos directory was not found at: {photosPath}");
            Console.WriteLine("Please create the directory and add some images.");
            return;
        }

        if (!Directory.EnumerateFileSystemEntries(photosPath).Any())
        {
            Console.WriteLine($"The Photos directory is empty: {photosPath}");
            Console.WriteLine("Please add some images (person1.jpg, person2.jpg, etc.)");
            return;
        }

        if (!File.Exists(arcfaceModel))
        {
            Console.WriteLine($"❌ ArcFace model not found at: {arcfaceModel}");
            Console.WriteLine("Please download arcface.onnx and place it in the Models directory.");
            return;
        }

        bool hasFaceDetection = File.Exists(faceDetectorProto) && File.Exists(faceDetectorModel);
        if (!hasFaceDetection)
        {
            Console.WriteLine("⚠ Face detection models not found. Running without face detection.");
            Console.WriteLine("For better accuracy, download the face detection models.");
        }

        // Find valid image files
        var imageFiles = Directory.GetFiles(photosPath, "*.*", SearchOption.TopDirectoryOnly)
            .Where(s => s.EndsWith(".jpg", StringComparison.OrdinalIgnoreCase) || 
                        s.EndsWith(".png", StringComparison.OrdinalIgnoreCase) || 
                        s.EndsWith(".jpeg", StringComparison.OrdinalIgnoreCase) ||
                        s.EndsWith(".webp", StringComparison.OrdinalIgnoreCase))
            .ToList();

        // Filter out problematic filenames
        var validImageFiles = new List<string>();
        var skippedFiles = new List<string>();

        foreach (var file in imageFiles)
        {
            string fileName = Path.GetFileName(file);

            if (file.Length > 250)
            {
                skippedFiles.Add($"{fileName} (path too long: {file.Length} chars)");
                continue;
            }

            if (fileName.Contains(".."))
            {
                skippedFiles.Add($"{fileName} (contains '..' which can cause issues)");
                continue;
            }

            validImageFiles.Add(file);
        }

        if (skippedFiles.Any())
        {
            Console.WriteLine("\n⚠ Warning: Some files were skipped:");
            foreach (var skipped in skippedFiles)
            {
                Console.WriteLine($"  - {skipped}");
            }
            Console.WriteLine("\nPlease rename to shorter names (e.g., person1.jpg).\n");
        }

        if (validImageFiles.Count < 1)
        {
            Console.WriteLine("No valid images found. Please add images to the Photos folder.");
            return;
        }

        Console.WriteLine($"Found {validImageFiles.Count} valid image(s) in the gallery.");

        // Randomly select a "wanted person"
        var random = new Random();
        int wantedIndex = random.Next(validImageFiles.Count);
        string wantedPersonImage = validImageFiles[wantedIndex];
        string wantedPersonName = Path.GetFileName(wantedPersonImage);
        Console.WriteLine($"\nWanted person is: {wantedPersonName}");
        Console.WriteLine();

        try
        {
            using var faceService = new ImprovedFaceRecognitionService(
                arcfaceModel, 
                hasFaceDetection ? faceDetectorProto : null,
                hasFaceDetection ? faceDetectorModel : null
            );

            // Process wanted person
            Console.WriteLine("\nProcessing wanted person image...");
            var wantedResult = faceService.GetEmbedding(wantedPersonImage);

            if (!wantedResult.Success)
            {
                Console.WriteLine($"❌ Could not process wanted person: {wantedResult.ErrorMessage}");
                return;
            }

            Console.WriteLine("✓ Face processed and encoded successfully.");
            Console.WriteLine("\nComparing against all people in the gallery...");
            Console.WriteLine("-------------------------------------------");

            // Compare with all other images
            bool found = false;
            var matches = new List<(string fileName, float similarity)>();
            var processed = 0;
            var failed = 0;

            foreach (var imagePath in validImageFiles)
            {
                if (imagePath == wantedPersonImage) continue;

                try
                {
                    var currentResult = faceService.GetEmbedding(imagePath);

                    if (!currentResult.Success)
                    {
                        Console.WriteLine($"File: {Path.GetFileName(imagePath),-30} | ⚠ {currentResult.ErrorMessage}");
                        failed++;
                        continue;
                    }

                    float similarity = ImprovedFaceRecognitionService.CosineSimilarity(
                        wantedResult.Embedding!, 
                        currentResult.Embedding!
                    );

                    // Adaptive threshold based on face detection
                    float threshold = hasFaceDetection ? 0.60f : 0.45f;
                    bool isMatch = similarity > threshold;
                    string result = isMatch ? "✓ MATCH!" : "✗ Different";

                    if (isMatch)
                    {
                        found = true;
                        matches.Add((Path.GetFileName(imagePath), similarity));
                    }

                    Console.WriteLine($"File: {Path.GetFileName(imagePath),-30} | Similarity: {similarity:F4} | {result}");
                    processed++;
                }
                catch (Exception ex)
                {
                    Console.WriteLine($"File: {Path.GetFileName(imagePath),-30} | Error: {ex.Message}");
                    failed++;
                }
            }

            // Display final results
            Console.WriteLine("\n" + new string('=', 70));
            Console.WriteLine("FINAL RESULTS");
            Console.WriteLine(new string('=', 70));
            Console.WriteLine($"Wanted Person: {wantedPersonName}");
            Console.WriteLine($"Face Detection: {(hasFaceDetection ? "Enabled ✓" : "Disabled")}");
            Console.WriteLine($"Matching Threshold: {(hasFaceDetection ? "0.60" : "0.45")}");
            Console.WriteLine($"Images Processed: {processed}");
            Console.WriteLine($"Images Failed: {failed}");
            Console.WriteLine();

            if (found)
            {
                Console.WriteLine($"✓ MATCH FOUND! We found {matches.Count} person(s) matching {wantedPersonName}:");
                Console.WriteLine();
                foreach (var match in matches.OrderByDescending(m => m.similarity))
                {
                    Console.WriteLine($"  🎯 {match.fileName,-30} (Confidence: {match.similarity:F4})");
                }
            }
            else
            {
                Console.WriteLine($"✗ NO MATCH - {wantedPersonName} was not found in the gallery.");
                Console.WriteLine("All other images appear to be different people.");
            }

            Console.WriteLine(new string('=', 70));
        }
        catch (Exception ex)
        {
            Console.WriteLine($"\n❌ Error: {ex.Message}");
            Console.WriteLine($"Stack trace:\n{ex.StackTrace}");
        }
    }

    private static string GetProjectRootDirectory()
    {
        string baseDirectory = AppContext.BaseDirectory;
        DirectoryInfo directory = new DirectoryInfo(baseDirectory);

        while (directory != null)
        {
            if (directory.GetFiles("*.csproj").Any())
            {
                return directory.FullName;
            }
            directory = directory.Parent;
        }

        return Path.GetFullPath(Path.Combine(baseDirectory, "..", "..", ".."));
    }
}

What This Code Does

Validates Setup - Checks for models and photos
Filters Images - Removes files with problematic names
Selects Target - Randomly picks a "wanted person"
Processes Faces - Generates embeddings for all images
Compares Embeddings - Uses cosine similarity
Reports Results - Shows matches with confidence scores

How It All Works Together

Let's trace through what happens when you run the program:

Step-by-Step Execution Flow

1. Program starts
   ↓
2. Load models (ArcFace + Face Detector)
   ↓
3. Find all images in Photos folder
   ↓
4. Randomly select "wanted person"
   ↓
5. For each image (including wanted person):
   ├── Load image from disk
   ├── [OpenCV] Detect face in image
   ├── [OpenCV] Crop to face region
   ├── [OpenCV] Resize to 112x112
   ├── [OpenCV] Normalize pixels
   ├── [ArcFace] Generate 512D embedding
   └── Store embedding
   ↓
6. Compare wanted person's embedding with all others:
   ├── Calculate cosine similarity
   ├── If similarity > threshold → MATCH
   └── If similarity < threshold → Different person
   ↓
7. Display results

The Math Behind Cosine Similarity

When comparing two embeddings, we use cosine similarity:

similarity = (A · B) / (||A|| × ||B||)

Since our embeddings are normalized (unit vectors), this simplifies to:

similarity = A · B  (dot product)

Interpreting scores:

0.70 - 1.00: Definitely the same person
0.60 - 0.70: Likely the same person (with face detection)
0.50 - 0.60: Possibly the same, could be siblings
0.40 - 0.50: Probably different people
0.00 - 0.40: Definitely different people

Why Face Detection Matters

Without face detection:

[Full Image] → ArcFace → Embedding includes background, hair, clothes
Result: person1.jpg vs person2.jpg might look similar if backgrounds match

With face detection:

[Full Image] → [Detect Face] → [Crop] → ArcFace → Embedding of facial features only
Result: Highly accurate comparison of actual facial features

This is why we can use a higher threshold (0.6) with face detection-it's more accurate!

Testing Your System

Prepare Test Images

You need at least 4-5 test images. Here's what works best:

Good test images:

✅ Clear face visible
✅ Face looking at camera
✅ Good lighting
✅ Minimal angle/tilt
✅ No sunglasses/masks

Images that work but are harder:

⚠️ Side profile (works at ~70% accuracy)
⚠️ Different lighting
⚠️ Different age (if many years apart)

Images that won't work:

❌ Face covered (mask, sunglasses)
❌ Face turned completely away
❌ Too blurry
❌ Face too small in image

Example Test Setup

Create test images in your Photos/ folder:

Photos/
├── person1.webp   ← Similar person
├── person2.jpg    ← Similar person
├── person3.webp   ← Similar person
├── person4.jpg    ← Different person
├── person5.webp   ← Different person
├── person6.webp   ← Different person
└── person7.webp   ← Different person

person1

person2

person3

person4

person5

person6

person7

All Together

Run the Demo

dotnet run

Expected Output

Perfect! It correctly identified that person1.jpg and person2.jpg are the similar person.

The Journey to Better Accuracy

Let me share the evolution of this system-what we tried and what actually worked.

Iteration 1: Basic ArcFace (No Face Detection)

Approach:

Feed entire images directly to ArcFace
Compare full-image embeddings

Results:

person1.jpg vs person2.jpg: 0.9721 (same person) ← Good!
person5.jpg vs person2.jpg: 0.9574 (different) ← FALSE POSITIVE!

Problem: Everything looked like a match! Why?

Background similarities
Clothing colors
Image composition
Hair styles

Accuracy: 100% false positive rate, horrible!!!!

Iteration 2: Tried FaceRecognitionDotNet (You may retry again!)

Approach:

Use dlib's face detection and recognition
Everything in one package

Results:

Build failed: Missing DLL files
DlibDotNetNativeDnnAgeClassification.dll not found
DlibDotNetNativeDnnGenderClassification.dll not found

Problem: Package was incomplete/broken for Windows

Decision: Abandoned this approach

Iteration 3: OpenCV DNN + ArcFace (Current Solution)

Approach:

Image → [OpenCV: Find Face] → [Crop] → [ArcFace: Embedding] → Compare

Results:

person1.jpg vs person3.jpg: 0.6513 (similar person) ← Correct!
person5.jpg vs person3.jpg: 0.4363 (different)   ← Correct!

Improvements:

Automatic face detection - No manual cropping needed
Focus on facial features - Ignore background/clothing
Higher threshold - 0.60 instead of 0.40
Fewer false positives - ~95% accuracy

Key Learnings

Face Localization is Critical - You must isolate the face from background
Model Quality Matters - ArcFace is one of the best face recognition models
Normalization is Essential - Both pixel normalization and vector normalization
Thresholds are Context-Dependent - With better preprocessing, use higher thresholds
Test with Real Data - Synthetic images often perform differently than real photos

Next Steps

Production Enhancements

Want to take this further? Here are some ideas:

1. Add a Database

Store embeddings in a database for fast searching:

public class FaceDatabase
{
    private readonly Dictionary<string, float[]> _embeddings = new();

    public void AddPerson(string name, float[] embedding)
    {
        _embeddings[name] = embedding;
    }

    public (string name, float confidence)? FindMatch(float[] queryEmbedding, float threshold = 0.6f)
    {
        string? bestMatch = null;
        float bestSimilarity = 0;

        foreach (var (name, embedding) in _embeddings)
        {
            float similarity = ImprovedFaceRecognitionService.CosineSimilarity(
                queryEmbedding, 
                embedding
            );

            if (similarity > threshold && similarity > bestSimilarity)
            {
                bestMatch = name;
                bestSimilarity = similarity;
            }
        }

        return bestMatch != null ? (bestMatch, bestSimilarity) : null;
    }
}

2. Real-Time Webcam Recognition

Process video frames in real-time:

using var capture = new VideoCapture(0); // Webcam
using Mat frame = new Mat();

while (true)
{
    capture.Read(frame);

    var result = faceService.GetEmbedding(frame);
    if (result.Success)
    {
        var match = database.FindMatch(result.Embedding!);
        // Display match on screen
    }
}

3. Face Recognition API

Build an ASP.NET Core Web API:

[ApiController]
[Route("api/[controller]")]
public class FaceRecognitionController : ControllerBase
{
    [HttpPost("compare")]
    public ActionResult<FaceComparisonResult> CompareFaces(
        IFormFile image1, 
        IFormFile image2)
    {
        // Process both images
        // Return similarity score
    }

    [HttpPost("identify")]
    public ActionResult<IdentificationResult> IdentifyPerson(IFormFile image)
    {
        // Compare against database
        // Return matched person
    }
}

4. Multi-Face Support

Detect and recognize multiple faces in one image:

public List<FaceEmbeddingResult> GetAllFaces(string imagePath)
{
    var faces = DetectAllFaces(image); // Returns list of Rect
    var results = new List<FaceEmbeddingResult>();

    foreach (var faceRect in faces)
    {
        var cropped = CropToRect(image, faceRect);
        var embedding = ProcessFaceForArcFace(cropped);
        results.Add(new FaceEmbeddingResult { Embedding = embedding });
    }

    return results;
}

5. Add Face Alignment

Improve accuracy by aligning eyes horizontally:

private Mat AlignFace(Mat face)
{
    // Detect facial landmarks (eyes, nose, mouth)
    var landmarks = DetectLandmarks(face);

    // Calculate rotation angle
    var leftEye = landmarks["left_eye"];
    var rightEye = landmarks["right_eye"];
    double angle = CalculateAngle(leftEye, rightEye);

    // Rotate image
    var center = new Point2f(face.Width / 2, face.Height / 2);
    var rotationMatrix = Cv2.GetRotationMatrix2D(center, angle, 1.0);

    Mat aligned = new Mat();
    Cv2.WarpAffine(face, aligned, rotationMatrix, face.Size());

    return aligned;
}

Performance Optimization

For production systems:

Batch Processing - Process multiple images at once
GPU Acceleration - Use Microsoft.ML.OnnxRuntime.Gpu
Caching - Cache embeddings to avoid recomputation
Parallel Processing - Use Parallel.ForEach for large datasets

Security Considerations

When deploying:

✅ Store embeddings, not original images
✅ Use HTTPS for API endpoints
✅ Implement rate limiting
✅ Add authentication/authorization
✅ Comply with privacy regulations (GDPR, etc.)

Conclusion

Congratulations! You've built a production-ready facial recognition system from scratch. Let's recap what we learned:

What We Built

✅ Face detection using OpenCV DNN
✅ Face recognition using ArcFace ONNX
✅ Similarity comparison with cosine similarity
✅ A complete demo application

Key Takeaways

Two Models, One Purpose - Face detection + face recognition work together
Embeddings are Powerful - Convert faces to comparable numerical vectors
Quality Matters - Better preprocessing = better accuracy
Thresholds are Tunable - Adjust based on your use case

The Tech Stack

C# & .NET 8 - Modern, fast, cross-platform
ONNX Runtime - Industry-standard model inference
OpenCV - Computer vision powerhouse
ArcFace - State-of-the-art face recognition

Going Further

This is just the beginning! You can now:

Build attendance systems
Create photo organization apps
Implement security systems
Develop person search tools

The code is ready for production-just add your specific business logic and deploy!

Resources

ArcFace Model: https://huggingface.co/garavv/arcface-onnx
OpenCV Models: https://github.com/opencv/opencv
ONNX Runtime: https://onnxruntime.ai/
OpenCvSharp: https://github.com/shimat/opencvsharp

Love C#!

Turn Plain English into Safe, Fast C# Rules with Ollama and Expression Trees

David Au Yeung — Mon, 15 Jun 2026 15:27:24 +0000

Introduction

Every now and then a feature request shows up that sounds innocent but is secretly a trap:

"Can users just type their rules in plain English and we run them?"

The lazy version of this is terrifying: ask an LLM to write C# code and then execute it. That's a one-way ticket to code injection, impossible-to-validate logic, and a security review that never ends.

So in this experiment we do the opposite. We keep the AI on a short leash and let it do the one thing it's genuinely great at - translating language - while our engine keeps full control of execution.

The flow is:

Natural language → AI → structured rule JSON → validate → expression tree → compiled Func<T, bool> → run

The AI never produces C#. It only produces data (JSON). Our code turns that validated data into a real, compiled delegate using one of my favorite tools in all of .NET: expression trees.

We will use:

.NET 8
OllamaSharp
http://localhost:11434
nemotron-3-super:cloud (any decent instruct model works)

And yes - there's a whole section near the end dedicated to this little line, because I think it's a genuinely beautiful piece of the framework:

return Expression.Lambda<Func<T, bool>>(body, parameter);

What We Are Building

User text: "wage must be at least 40 and hours must not exceed 60"
  -> AiRuleParser  (reuses your Ollama chat service)
  -> Ollama (nemotron-3-super:cloud)
  -> Rule JSON (strict schema)
  -> RuleNodeJsonConverter (validate + deserialize)
  -> RuleExpressionBuilder (whitelist fields + operators)
  -> Expression<Func<Employee, bool>>
  -> .Compile()
  -> Func<Employee, bool>
  -> run against your data

The key idea, stated bluntly:

⚠️ AI never generates C# code
✅ AI only generates structured JSON
✅ Your system converts JSON → compiled code, safely

The Golden Rule: AI Writes Data, Not Code

If you let the model emit C#:

❌ Code injection
❌ Impossible to validate
❌ Impossible to restrict

If you let the model emit JSON that conforms to a schema you own:

✅ Safe (you choose which operators/fields exist)
✅ Validatable (bad JSON is rejected)
✅ Deterministic (same shape every time)
✅ You stay in control

Everything below is just a faithful implementation of that one principle.

Prerequisites

Visual Studio or VS Code
.NET 8 SDK
Ollama running locally
A model pulled into your Ollama environment

Run Ollama with the model used in this demo:

ollama run nemotron-3-super:cloud

If your Ollama service is already running at http://localhost:11434, you are good.

Step 1: Create a New Console App

dotnet new console -n AiRuleEngineDemo
cd AiRuleEngineDemo
dotnet add package OllamaSharp

Step 2: Project File (Reference)

Your .csproj should include at least:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="OllamaSharp" Version="5.4.25" />
  </ItemGroup>
</Project>

No System.Text.Json or System.Linq.Expressions package needed - both ship in the BCL.

Step 3: Define the Rule Model (the AST)

This is the only shape the AI is ever allowed to produce. Three node types:

a comparison (Wage >= 40)
an and group
an or group

using System.Text.Json.Serialization;

namespace AiRuleEngine;

// Structured rule model (an AST). The AI only ever produces one of these shapes
// as JSON - it never produces executable C#. The engine is what turns this
// validated data into a compiled delegate.
[JsonConverter(typeof(RuleNodeJsonConverter))]
public abstract class RuleNode
{
    // Discriminator: "comparison", "and", or "or".
    public string Type { get; set; } = string.Empty;
}

public sealed class ComparisonRule : RuleNode
{
    public string Field { get; set; } = string.Empty;
    public string Operator { get; set; } = string.Empty;
    public decimal Value { get; set; }
}

public sealed class LogicalRule : RuleNode
{
    public List<RuleNode> Rules { get; set; } = new();
}

A nested rule like "wage ≥ 40 AND hours ≤ 60" serializes to:

{
  "type": "and",
  "rules": [
    { "type": "comparison", "field": "Wage",  "operator": ">=", "value": 40 },
    { "type": "comparison", "field": "Hours", "operator": "<=", "value": 60 }
  ]
}

Step 4: Teach JSON How to Be Polymorphic

There's one wrinkle: both "and" and "or" map to the same LogicalRule type, so the built-in [JsonDerivedType] attribute won't cut it (it needs a unique discriminator per type). A small custom converter handles it - and conveniently gives us a home for the "strip Markdown fences" helper, because local models love wrapping JSON in

```json

.

using System.Globalization;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Text.RegularExpressions;

namespace AiRuleEngine;

public sealed class RuleNodeJsonConverter : JsonConverter<RuleNode>
{
    public override RuleNode Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        using var document = JsonDocument.ParseValue(ref reader);
        return ReadElement(document.RootElement, options);
    }

    private static RuleNode ReadElement(JsonElement element, JsonSerializerOptions options)
    {
        if (element.ValueKind != JsonValueKind.Object)
        {
            throw new JsonException("Each rule node must be a JSON object.");
        }

        if (!element.TryGetProperty("type", out var typeProperty) ||
            typeProperty.ValueKind != JsonValueKind.String)
        {
            throw new JsonException("Rule node is missing a required string 'type' property.");
        }

        var type = typeProperty.GetString()!.Trim().ToLowerInvariant();

        return type switch
        {
            "comparison" => ReadComparison(element),
            "and" or "or" => ReadLogical(element, type, options),
            _ => throw new JsonException($"Unsupported rule type '{type}'. Allowed: comparison, and, or.")
        };
    }

    private static ComparisonRule ReadComparison(JsonElement element)
    {
        if (!element.TryGetProperty("field", out var field) || field.ValueKind != JsonValueKind.String)
        {
            throw new JsonException("Comparison rule requires a string 'field'.");
        }

        if (!element.TryGetProperty("operator", out var op) || op.ValueKind != JsonValueKind.String)
        {
            throw new JsonException("Comparison rule requires a string 'operator'.");
        }

        if (!element.TryGetProperty("value", out var value))
        {
            throw new JsonException("Comparison rule requires a 'value'.");
        }

        return new ComparisonRule
        {
            Type = "comparison",
            Field = field.GetString()!,
            Operator = op.GetString()!,
            Value = ReadDecimal(value)
        };
    }

    private static LogicalRule ReadLogical(JsonElement element, string type, JsonSerializerOptions options)
    {
        var rules = new List<RuleNode>();

        if (element.TryGetProperty("rules", out var rulesElement) &&
            rulesElement.ValueKind == JsonValueKind.Array)
        {
            foreach (var child in rulesElement.EnumerateArray())
            {
                rules.Add(ReadElement(child, options));
            }
        }

        if (rules.Count == 0)
        {
            throw new JsonException($"Logical rule '{type}' must contain at least one child rule.");
        }

        return new LogicalRule { Type = type, Rules = rules };
    }

    private static decimal ReadDecimal(JsonElement element)
    {
        return element.ValueKind switch
        {
            JsonValueKind.Number => element.GetDecimal(),
            JsonValueKind.String when decimal.TryParse(
                element.GetString(), NumberStyles.Any, CultureInfo.InvariantCulture, out var parsed) => parsed,
            _ => throw new JsonException("Comparison 'value' must be a number.")
        };
    }

    public override void Write(Utf8JsonWriter writer, RuleNode value, JsonSerializerOptions options)
    {
        switch (value)
        {
            case ComparisonRule comparison:
                writer.WriteStartObject();
                writer.WriteString("type", "comparison");
                writer.WriteString("field", comparison.Field);
                writer.WriteString("operator", comparison.Operator);
                writer.WriteNumber("value", comparison.Value);
                writer.WriteEndObject();
                break;

            case LogicalRule logical:
                writer.WriteStartObject();
                writer.WriteString("type", logical.Type);
                writer.WritePropertyName("rules");
                writer.WriteStartArray();
                foreach (var child in logical.Rules)
                {
                    Write(writer, child, options);
                }
                writer.WriteEndArray();
                writer.WriteEndObject();
                break;

            default:
                throw new JsonException($"Unknown rule node type '{value.GetType().Name}'.");
        }
    }

    // Local models often wrap JSON in prose or Markdown fences. Strip them and
    // extract the outermost JSON object so deserialization stays robust.
    public static string ExtractJsonObject(string text)
    {
        if (string.IsNullOrWhiteSpace(text))
        {
            throw new FormatException("Model returned an empty response.");
        }

        var cleaned = text.Trim();
        cleaned = Regex.Replace(cleaned, "^```
{% endraw %}
(?:json)?\\s*", string.Empty, RegexOptions.IgnoreCase);
        cleaned = Regex.Replace(cleaned, "\\s*
{% raw %}
```$", string.Empty, RegexOptions.IgnoreCase);

        var start = cleaned.IndexOf('{');
        var end = cleaned.LastIndexOf('}');

        if (start < 0 || end <= start)
        {
            throw new FormatException("No JSON object found in model response.");
        }

        return cleaned[start..(end + 1)];
    }
}

Step 5: The Heart of It - Compile Rules with Expression Trees

This is the safety boundary and the performance trick. The AI handed us data; here we decide exactly which fields and operators are legal, and we assemble a real lambda from them.

using System.Linq.Expressions;
using System.Reflection;

namespace AiRuleEngine;

public static class RuleExpressionBuilder
{
    private static readonly string[] AllowedOperators = { ">", ">=", "<", "<=", "==", "!=" };

    // allowedFields (optional) restricts which properties of T a rule may touch.
    public static Expression<Func<T, bool>> BuildExpression<T>(
        RuleNode node,
        ISet<string>? allowedFields = null)
    {
        ArgumentNullException.ThrowIfNull(node);

        var parameter = Expression.Parameter(typeof(T), "x");
        var body = Build(node, parameter, allowedFields);
        return Expression.Lambda<Func<T, bool>>(body, parameter);
    }

    private static Expression Build(RuleNode node, ParameterExpression parameter, ISet<string>? allowedFields)
    {
        return node switch
        {
            ComparisonRule comparison => BuildComparison(comparison, parameter, allowedFields),
            LogicalRule logical => BuildLogical(logical, parameter, allowedFields),
            _ => throw new InvalidOperationException($"Unsupported rule node '{node.GetType().Name}'.")
        };
    }

    private static Expression BuildComparison(
        ComparisonRule comparison,
        ParameterExpression parameter,
        ISet<string>? allowedFields)
    {
        if (!AllowedOperators.Contains(comparison.Operator))
        {
            throw new InvalidOperationException(
                $"Operator '{comparison.Operator}' is not allowed. Allowed: {string.Join(", ", AllowedOperators)}.");
        }

        var property = ResolveProperty(parameter.Type, comparison.Field, allowedFields);
        var propertyAccess = Expression.Property(parameter, property);

        // Coerce the rule's decimal value into the property's actual type so the
        // comparison operands match (e.g. decimal -> int / double / decimal).
        var typedValue = Convert.ChangeType(comparison.Value, property.PropertyType);
        var constant = Expression.Constant(typedValue, property.PropertyType);

        return comparison.Operator switch
        {
            ">" => Expression.GreaterThan(propertyAccess, constant),
            ">=" => Expression.GreaterThanOrEqual(propertyAccess, constant),
            "<" => Expression.LessThan(propertyAccess, constant),
            "<=" => Expression.LessThanOrEqual(propertyAccess, constant),
            "==" => Expression.Equal(propertyAccess, constant),
            "!=" => Expression.NotEqual(propertyAccess, constant),
            _ => throw new InvalidOperationException($"Operator '{comparison.Operator}' is not supported.")
        };
    }

    private static Expression BuildLogical(
        LogicalRule logical,
        ParameterExpression parameter,
        ISet<string>? allowedFields)
    {
        if (logical.Rules is null || logical.Rules.Count == 0)
        {
            throw new InvalidOperationException("Logical rule must contain at least one child rule.");
        }

        var childExpressions = logical.Rules
            .Select(child => Build(child, parameter, allowedFields))
            .ToList();

        return logical.Type.ToLowerInvariant() switch
        {
            "and" => childExpressions.Aggregate(Expression.AndAlso),
            "or" => childExpressions.Aggregate(Expression.OrElse),
            _ => throw new InvalidOperationException($"Unsupported logical type '{logical.Type}'.")
        };
    }

    private static PropertyInfo ResolveProperty(Type type, string field, ISet<string>? allowedFields)
    {
        if (string.IsNullOrWhiteSpace(field))
        {
            throw new InvalidOperationException("Comparison rule is missing a field name.");
        }

        // Case-insensitive lookup tolerates the model's casing while still only
        // binding to a real, public property (no arbitrary reflection).
        var property = type.GetProperty(
            field, BindingFlags.Public | BindingFlags.Instance | BindingFlags.IgnoreCase)
            ?? throw new InvalidOperationException($"Field '{field}' does not exist on type '{type.Name}'.");

        if (allowedFields is not null && !allowedFields.Contains(property.Name))
        {
            throw new InvalidOperationException($"Field '{property.Name}' is not in the allowed field list.");
        }

        return property;
    }
}

Three layers of safety live in this file:

Operator whitelist - only the six operators we listed can ever exist.
Field whitelist + existence check - a rule can only touch a real, allowed property. No reflection on arbitrary names.
Type coercion - the model's number is converted to the property's real type before we build the comparison.

Now for the line I promised…

⭐ The One Line That Makes the Magic: `Expression.Lambda<Func<T, bool>>(body, parameter)`

Honestly? This is my favorite line in the whole project:

return Expression.Lambda<Func<T, bool>>(body, parameter);

It looks tiny, but it's doing something kind of wonderful: we are building C# at runtime, with code.

Unpacking it

When you write a normal lambda by hand:

Func<Employee, bool> isMatch = x => x.Wage >= 40 && x.Hours <= 60;

the compiler quietly splits x => ... into two pieces:

a parameter - the x
a body - the boolean expression x.Wage >= 40 && x.Hours <= 60

Expression trees let us build those exact two pieces ourselves, as data:

parameter is Expression.Parameter(typeof(T), "x") - that's the x.
body is the boolean tree we assembled from the rule (GreaterThanOrEqual, AndAlso, …).

Then this:

Expression.Lambda<Func<T, bool>>(body, parameter)

stitches them into a complete lambda as an object - an Expression<Func<T, bool>>. It is not running yet. It's a description of x => body, sitting in memory, that you can inspect, log, cache, or store.

Print it and you literally see the code you assembled:

x => ((x.Wage >= 40) AndAlso (x.Hours <= 60))

The payoff: `.Compile()`

var isMatch = expression.Compile();

.Compile() turns that tree into a real delegate - actual IL, the same kind the compiler emits for a hand-written lambda. Compile it once, and from then on isMatch(employee) runs at basically hand-written speed. No reflection per call. No interpreter. No eval.

Why I keep calling it "a really good tool"

Because it gives you four things at the same time:

Safe 🔒 - you only ever build the operators you allow (GreaterThan, AndAlso, …). There's no path to "run arbitrary C#," unlike string-eval or Roslyn scripting. The AI literally cannot inject code, because it never emits code.
Fast ⚡ - compile once, run millions of times. Perfect for rule engines, filters, pricing, and policy checks.
Composable 🧩 - and/or are just Expression.AndAlso / Expression.OrElse over child expressions, so nesting falls right out of recursion.
Inspectable 🔎 - expression.ToString() is a free audit log and a fantastic debugging aid.

A mental model for the whole round trip:

RuleNode (data)
   -> Expression pieces (parameter + body)
   -> Expression.Lambda<Func<T,bool>>(...)   // code as data
   -> .Compile()                              // data becomes a live delegate
   -> isMatch(employee)                       // runs at native speed

That journey - data → expression → compiled delegate - is the entire trick that makes "natural language to executable rule" both safe and fast.

Bonus: it composes with EF Core

Because Expression<Func<T, bool>> is exactly what IQueryable<T>.Where(...) accepts, the very same rule you built from a sentence can be pushed down into a database query and translated to SQL - instead of pulling rows into memory. One representation, two execution targets. That's the kind of leverage you don't get from a string interpreter.

Step 6: Reuse Your Ollama Service (Natural Language → JSON)

Here's where we "reuse the Ollama service." The parser depends on a tiny IChatbot abstraction - so if you already have an Ollama chat wrapper in your app, just implement IChatbot on it and pass it in. For a self-contained demo, here's a minimal OllamaSharp-backed adapter:

using OllamaSharp;
using System.Text;

namespace AiRuleEngine;

public interface IChatbot
{
    Task<string> AskQuestion(string userMessage);
}

// Minimal Ollama-backed chat service. Already have one? Implement IChatbot
// on your existing class and reuse it instead.
public sealed class OllamaChatbot : IChatbot
{
    private readonly OllamaApiClient _client;

    public OllamaChatbot(string endpoint, string model)
    {
        _client = new OllamaApiClient(new Uri(endpoint)) { SelectedModel = model };
    }

    public async Task<string> AskQuestion(string userMessage)
    {
        var builder = new StringBuilder();

        await foreach (var chunk in _client.GenerateAsync(userMessage))
        {
            if (!string.IsNullOrWhiteSpace(chunk?.Response))
            {
                builder.Append(chunk.Response);
            }
        }

        return builder.ToString();
    }
}

And the parser itself - it builds the prompt, asks the model, extracts the JSON, and deserializes:

using System.Text;
using System.Text.Json;

namespace AiRuleEngine;

public sealed class AiRuleParser
{
    private static readonly JsonSerializerOptions SerializerOptions = new()
    {
        PropertyNameCaseInsensitive = true
    };

    private readonly IChatbot _chatbot;

    public AiRuleParser(IChatbot chatbot)
    {
        _chatbot = chatbot ?? throw new ArgumentNullException(nameof(chatbot));
    }

    // Convenience: derive the schema straight from the target type.
    public Task<RuleNode> ParseAsync<T>(string naturalLanguageRule)
        => ParseAsync(naturalLanguageRule, RuleSchema.FromType<T>());

    public async Task<RuleNode> ParseAsync(string naturalLanguageRule, RuleSchema? schema = null)
    {
        if (string.IsNullOrWhiteSpace(naturalLanguageRule))
        {
            throw new ArgumentException("Rule text must be provided.", nameof(naturalLanguageRule));
        }

        var prompt = BuildPrompt(naturalLanguageRule, schema);
        var rawResponse = await _chatbot.AskQuestion(prompt);
        var json = RuleNodeJsonConverter.ExtractJsonObject(rawResponse ?? string.Empty);

        return JsonSerializer.Deserialize<RuleNode>(json, SerializerOptions)
            ?? throw new FormatException("Model response did not deserialize into a rule.");
    }

    private static string BuildPrompt(string naturalLanguageRule, RuleSchema? schema)
    {
        var builder = new StringBuilder();
        builder.AppendLine("Convert the following business rule into strict JSON.");
        builder.AppendLine("Output JSON only. Do not include explanations or Markdown fences.");
        builder.AppendLine();
        builder.AppendLine("Supported node types: \"comparison\", \"and\", \"or\".");
        builder.AppendLine("Supported operators: \">\", \">=\", \"<\", \"<=\", \"==\", \"!=\".");
        builder.AppendLine("Every comparison \"value\" must be a number, so only compare numeric fields.");
        builder.AppendLine();
        builder.AppendLine("A comparison node looks like:");
        builder.AppendLine("{ \"type\": \"comparison\", \"field\": \"Wage\", \"operator\": \">=\", \"value\": 40 }");
        builder.AppendLine();
        builder.AppendLine("An and/or node groups child rules:");
        builder.AppendLine("{ \"type\": \"and\", \"rules\": [ { ...comparison... }, { ...comparison... } ] }");

        // Feed the schema so the model uses real fields and correct casing.
        if (schema is not null && schema.Fields.Count > 0)
        {
            builder.AppendLine();
            builder.AppendLine(schema.ToPromptDescription());
            builder.AppendLine();
            builder.AppendLine("Only use the fields listed above and match their casing exactly.");
        }

        builder.AppendLine();
        builder.AppendLine("Rule:");
        builder.Append(naturalLanguageRule);

        return builder.ToString();
    }
}

Step 7: Give the Model a Schema (So It Stops Guessing)

Passing just field names is the bare minimum. The model does noticeably better when it also knows each field's type (and ideally a short description). Even better: derive the schema and the whitelist from the target type via reflection, so they can never drift apart.

using System.ComponentModel;
using System.Reflection;
using System.Text;

namespace AiRuleEngine;

public sealed class RuleField
{
    public RuleField(string name, string typeName, string? description = null)
    {
        Name = name;
        TypeName = typeName;
        Description = description;
    }

    public string Name { get; }
    public string TypeName { get; }       // friendly: "number", "text", "date", "boolean"
    public string? Description { get; }
}

public sealed class RuleSchema
{
    private RuleSchema(IReadOnlyList<RuleField> fields)
    {
        Fields = fields;
        FieldNames = new HashSet<string>(fields.Select(f => f.Name), StringComparer.OrdinalIgnoreCase);
    }

    public IReadOnlyList<RuleField> Fields { get; }

    // Pass directly to RuleExpressionBuilder.BuildExpression as the whitelist.
    public ISet<string> FieldNames { get; }

    public static RuleSchema FromType<T>() => FromType(typeof(T));

    public static RuleSchema FromType(Type type)
    {
        var fields = type
            .GetProperties(BindingFlags.Public | BindingFlags.Instance)
            .Where(p => p.CanRead && p.GetIndexParameters().Length == 0)
            .Select(p => new RuleField(
                p.Name,
                DescribeType(p.PropertyType),
                p.GetCustomAttribute<DescriptionAttribute>()?.Description))
            .ToList();

        return new RuleSchema(fields);
    }

    public string ToPromptDescription()
    {
        var builder = new StringBuilder();
        builder.AppendLine("Available fields (use the exact names and respect the types):");

        foreach (var field in Fields)
        {
            builder.Append("- ").Append(field.Name).Append(" (").Append(field.TypeName).Append(')');
            if (!string.IsNullOrWhiteSpace(field.Description))
            {
                builder.Append(" - ").Append(field.Description);
            }
            builder.AppendLine();
        }

        return builder.ToString().TrimEnd();
    }

    private static string DescribeType(Type type)
    {
        var underlying = Nullable.GetUnderlyingType(type) ?? type;

        if (underlying.IsEnum) return $"text (one of: {string.Join(", ", Enum.GetNames(underlying))})";
        if (underlying == typeof(bool)) return "boolean";
        if (underlying == typeof(DateTime) || underlying == typeof(DateTimeOffset) || underlying == typeof(DateOnly)) return "date";
        if (underlying == typeof(string) || underlying == typeof(char)) return "text";

        if (underlying == typeof(byte) || underlying == typeof(sbyte) ||
            underlying == typeof(short) || underlying == typeof(ushort) ||
            underlying == typeof(int) || underlying == typeof(uint) ||
            underlying == typeof(long) || underlying == typeof(ulong) ||
            underlying == typeof(float) || underlying == typeof(double) ||
            underlying == typeof(decimal)) return "number";

        return underlying.Name.ToLowerInvariant();
    }
}

With this, the prompt grows from a flat list of names into something the model can actually reason about:

Available fields (use the exact names and respect the types):
- Name (text)
- Wage (number) - Hourly pay rate in dollars
- Hours (number) - Hours worked per week
- Age (number) - Age in years

Step 8: Wire Up the Demo in `Program.cs`

using AiRuleEngine;
using System.ComponentModel;
using System.Text;
using System.Text.Encodings.Web;
using System.Text.Json;

Console.OutputEncoding = Encoding.UTF8;

const string endpoint = "http://localhost:11434";
const string model = "nemotron-3-super:cloud";

// Reuse YOUR Ollama chat service here. Anything that implements IChatbot works.
IChatbot ollama = new OllamaChatbot(endpoint, model);
var parser = new AiRuleParser(ollama);

// Single source of truth: schema + whitelist both come from the type.
var schema = RuleSchema.FromType<Employee>();

Console.WriteLine("Describe a rule in plain English.");
Console.WriteLine("Example: wage must be at least 40 and hours must not exceed 60");
Console.Write("> ");

var input = Console.ReadLine();
if (string.IsNullOrWhiteSpace(input))
{
    input = "wage must be at least 40 and hours must not exceed 60";
    Console.WriteLine($"(no input - using sample rule: \"{input}\")");
}

var ruleNode = await parser.ParseAsync(input, schema);

// Audit log: show the structured JSON the AI produced.
// UnsafeRelaxedJsonEscaping keeps operators readable (>= instead of \u003E=).
var auditJson = JsonSerializer.Serialize(ruleNode, new JsonSerializerOptions
{
    WriteIndented = true,
    Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping
});
Console.WriteLine();
Console.WriteLine("AI-generated rule JSON:");
Console.WriteLine(auditJson);

// The star of the show: build the expression, then compile it.
var expression = RuleExpressionBuilder.BuildExpression<Employee>(ruleNode, schema.FieldNames);
Console.WriteLine();
Console.WriteLine($"Compiled expression: {expression}");

var isMatch = expression.Compile();

var employees = new[]
{
    new Employee { Name = "Alice", Wage = 45m, Hours = 55m, Age = 31 },
    new Employee { Name = "Bob",   Wage = 35m, Hours = 50m, Age = 27 },
    new Employee { Name = "Carol", Wage = 50m, Hours = 65m, Age = 44 }
};

Console.WriteLine();
Console.WriteLine("Evaluation:");
foreach (var e in employees)
{
    Console.WriteLine($"  {e.Name,-6} Wage={e.Wage,-5} Hours={e.Hours,-5} Age={e.Age,-3} => {isMatch(e)}");
}

public sealed class Employee
{
    public string Name { get; set; } = string.Empty;

    [Description("Hourly pay rate in dollars")]
    public decimal Wage { get; set; }

    [Description("Hours worked per week")]
    public decimal Hours { get; set; }

    [Description("Age in years")]
    public int Age { get; set; }
}

Step 9: Run It

dotnet run

Type a rule (or press Enter to use the sample). A typical session looks like this:

Notice the middle line - that's our expression tree printing itself back out. The AI gave us data; we turned it into running code.

Why Expression Trees Beat the Alternatives

Approach	Safe?	Fast?	Notes
Ask the LLM for C#, then run it	❌	-	Code injection; impossible to validate; never ship this
Roslyn scripting (`CSharpScript`)	❌	➖	Compiles arbitrary C#; heavy; same injection surface
String rule interpreter	➖	❌	You reinvent a parser; re-parses every evaluation
Reflection per evaluation	✅	❌	Safe but slow; reflection cost on every call
Expression tree + `.Compile()`	✅	✅	Whitelisted operations, compiled once, native speed, inspectable

Why This Is a Fun (and Safe) Experiment

You let users write rules in plain English without handing them a keyboard into your runtime.
The AI stays in its lane: translation only, never execution.
Every generated rule is auditable - store the original text, the AI JSON, and the compiled ToString().
The same Expression<Func<T, bool>> works in-memory and against IQueryable/EF Core.
It's a tiny, satisfying demo of "code as data" that you can extend in a dozen directions.

Notes and Limitations

This demo compares numbers only (ComparisonRule.Value is decimal). To support text/date/boolean, widen the value model and add the matching Expression operators.
Small local models occasionally wander off-schema. The fence-stripping + JSON extraction helper covers the common cases; for production, add JSON-schema validation and a validate → repair loop that feeds the validation error back to the model for one retry.
Cache compiled delegates keyed by the rule JSON if you evaluate the same rule a lot - compile once, reuse forever.
Keep the field whitelist tight. It's your last line of defense even though the AI never emits code.

Closing

The whole idea fits in one sentence:

Let the AI translate, and let expression trees execute.

Start from a sentence, get back strict JSON, validate it, and compile it into a real Func<T, bool> with this lovely little line:

return Expression.Lambda<Func<T, bool>>(body, parameter);

Safe, fast, composable, inspectable. That's why I think it's a really good tool too.

Love C#!

Step-by-Step Guide: Connect Blazor to Device Camera with JavaScript Interop and Face Recognition Logic

David Au Yeung — Sun, 07 Jun 2026 12:20:32 +0000

Introduction

In my previous article, Step-by-Step Guide: Build a CRUD Blazor App with Entity Framework and PostgreSQL, we focused on data basics and CRUD flow.

In this article, we move to a practical AI patrol scenario: connect a Blazor web app to a device camera, send image frames to backend APIs, and display match alerts in real time. We will also explain how Blazor interacts with JavaScript, the face recognition logic behind the current demo, and the SQL DbStrategy design.

The project is now renamed to AIPatrolCamera.

This demo is built with .NET 10 and can be developed with VS Code.

Prerequisites

Before we begin, make sure you have:

.NET 10 SDK installed
VS Code + C# Dev Kit extension
A modern browser (Chrome/Edge recommended)
PostgreSQL (or use SQLite fallback from configuration)
Basic understanding of Blazor components and dependency injection

Step 1: Open and run AIPatrolCamera in VS Code

Open terminal in VS Code:

cd AIPatrolCamera
dotnet restore
dotnet run

If startup succeeds, open the URL shown in the terminal and navigate to /patrol.

Step 2: Understand the camera page in Blazor

The page is implemented in Components/Pages/Patrol.razor.

Key UI elements:

<video id="video"> for live camera preview
<canvas id="canvas" class="d-none"> for snapshot capture
A start button that triggers patrol mode
An alert box shown when backend detects a match

Patrol page uses:

@rendermode InteractiveServer
IJSRuntime for JS interop
[JSInvokable] method ShowAlert(...) so JavaScript can call back into .NET

This is the core bridge between Blazor UI and browser camera APIs.

Detailed coding (`Components/Pages/Patrol.razor`)

@page "/patrol"
@rendermode InteractiveServer
@implements IAsyncDisposable

<PageTitle>Patrol</PageTitle>

<h1>AI Patrol Mode</h1>

<video id="video" autoplay playsinline class="patrol-video"></video>
<canvas id="canvas" class="d-none"></canvas>

@if (alertVisible)
{
    <div class="alert-box" role="alert" aria-live="assertive">
        <h2>⚠ MATCH FOUND</h2>
        <p><strong>Name:</strong> @alertName</p>
        <p><strong>Risk:</strong> @alertRisk</p>
        <p><strong>Action:</strong> @alertInstruction</p>
    </div>
}

<button class="btn btn-danger mt-3" @onclick="StartPatrolAsync">Start Patrol</button>

@code {
    private bool alertVisible;
    private string alertName = string.Empty;
    private string alertRisk = string.Empty;
    private string alertInstruction = string.Empty;
    private DotNetObjectReference<Patrol>? dotNetReference;
    private bool isInteractive;

    [Inject]
    private IJSRuntime JS { get; set; } = default!;

    protected override void OnAfterRender(bool firstRender)
    {
        if (firstRender)
        {
            isInteractive = true;
        }
    }

    private async Task StartPatrolAsync()
    {
        dotNetReference ??= DotNetObjectReference.Create(this);
        await JS.InvokeVoidAsync("patrolCamera.start", dotNetReference);
    }

    [JSInvokable]
    public Task ShowAlert(string name, string riskLevel, string instruction)
    {
        alertName = name;
        alertRisk = riskLevel;
        alertInstruction = instruction;
        alertVisible = true;
        StateHasChanged();
        return Task.CompletedTask;
    }

    public async ValueTask DisposeAsync()
    {
        if (!isInteractive)
        {
            dotNetReference?.Dispose();
            return;
        }

        try
        {
            await JS.InvokeVoidAsync("patrolCamera.stop");
        }
        catch (JSDisconnectedException)
        {
        }

        dotNetReference?.Dispose();
    }
}

Step 3: Understand Blazor ↔ JavaScript interop flow

In Patrol.razor, when user clicks Start Patrol, Blazor executes:

await JS.InvokeVoidAsync("patrolCamera.start", dotNetReference);

This calls JavaScript function window.patrolCamera.start(...) in wwwroot/js/patrolCamera.js.

Inside JS:

Request camera stream from browser:

   navigator.mediaDevices.getUserMedia({ video: true })

Bind stream to <video>
Start timer (setInterval) every 3 seconds
Draw current frame to canvas
Convert frame to Base64 image with canvas.toDataURL("image/jpeg")
POST to backend API /api/detect
If match found, call C# method:

   dotNetHelper.invokeMethodAsync("ShowAlert", ...)

In short:

Blazor calls JS to access browser-only capability (camera)
JS calls Blazor to update component state (alert rendering)

This two-way interop is the most important pattern when working with hardware features in web apps.

Detailed coding (`wwwroot/js/patrolCamera.js`)

window.patrolCamera = (() => {
    let dotNetHelper = null;
    let stream = null;
    let captureTimer = null;

    async function start(helper) {
        dotNetHelper = helper;

        const video = document.getElementById("video");
        if (!video) {
            return;
        }

        if (captureTimer) {
            clearInterval(captureTimer);
            captureTimer = null;
        }

        stream = await navigator.mediaDevices.getUserMedia({ video: true });
        video.srcObject = stream;

        captureTimer = setInterval(captureFrame, 3000);
    }

    async function captureFrame() {
        const video = document.getElementById("video");
        const canvas = document.getElementById("canvas");

        if (!video || !canvas || !dotNetHelper || video.videoWidth === 0 || video.videoHeight === 0) {
            return;
        }

        const context = canvas.getContext("2d");
        if (!context) {
            return;
        }

        canvas.width = video.videoWidth;
        canvas.height = video.videoHeight;
        context.drawImage(video, 0, 0);

        const image = canvas.toDataURL("image/jpeg");

        const response = await fetch("/api/detect", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ image })
        });

        if (!response.ok) {
            return;
        }

        const result = await response.json();
        if (result?.match) {
            await dotNetHelper.invokeMethodAsync(
                "ShowAlert",
                result.name ?? "Unknown",
                result.riskLevel ?? "Unknown",
                result.instruction ?? "Observe and Report");
        }
    }

    function stop() {
        if (captureTimer) {
            clearInterval(captureTimer);
            captureTimer = null;
        }

        if (stream) {
            for (const track of stream.getTracks()) {
                track.stop();
            }
            stream = null;
        }

        dotNetHelper = null;
    }

    return { start, stop };
})();

Also ensure JS file is loaded in Components/App.razor:

<script src="@Assets["js/patrolCamera.js"]"></script>
<script src="@Assets["_framework/blazor.web.js"]"></script>

Step 4: Explain camera permission and authority best practices

When your page calls getUserMedia, browser asks user permission to use camera.

Please remind readers:

Always request camera access only after explicit user action (for example clicking Start Patrol)

Explain clearly why camera is needed
Provide a visible stop action and actually stop tracks (track.stop())
Use HTTPS in non-local environments (camera APIs are restricted in insecure contexts)
Avoid capturing or sending frames when patrol is not active
Do not store sensitive data unless users have agreed

Good authority handling improves trust and keeps your app aligned with privacy expectations.

Step 5: Backend detection endpoint and current demo logic

Backend API is Controllers/DetectController.cs:

Accepts ImageRequest
Calls FaceRecognitionService.DetectAsync(...)
Returns DetectResponse

Current FaceRecognitionService is a demo implementation:

Decodes incoming Base64 image
Reads first person from database
Returns a simulated match response

So right now, it is a pipeline demo (camera → API → UI alert), not real AI face embedding comparison yet.

This is still useful because architecture and data flow are already valid.

Detailed coding (`Controllers/DetectController.cs`)

[ApiController]
[Route("api/[controller]")]
public class DetectController(FaceRecognitionService faceRecognitionService) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> Detect([FromBody] ImageRequest request, CancellationToken cancellationToken)
    {
        if (request is null)
        {
            return BadRequest();
        }

        var result = await faceRecognitionService.DetectAsync(request.Image, cancellationToken);
        return Ok(result);
    }
}

Detailed coding (`Services/FaceRecognitionService.cs`) - current demo behavior

public class FaceRecognitionService(AppDbContext dbContext)
{
    public async Task<DetectResponse> DetectAsync(string imageData, CancellationToken cancellationToken)
    {
        if (string.IsNullOrWhiteSpace(imageData))
        {
            return new DetectResponse { Match = false };
        }

        var imageBytes = TryDecodeBase64(imageData);
        if (imageBytes is null || imageBytes.Length == 0)
        {
            return new DetectResponse { Match = false };
        }

        var firstKnownPerson = await dbContext.People
            .AsNoTracking()
            .OrderBy(x => x.Id)
            .FirstOrDefaultAsync(cancellationToken);

        if (firstKnownPerson is null)
        {
            return new DetectResponse
            {
                Match = true,
                Name = "Test Person",
                RiskLevel = "Medium",
                Instruction = "Observe and Report"
            };
        }

        return new DetectResponse
        {
            Match = true,
            Name = firstKnownPerson.Name,
            RiskLevel = firstKnownPerson.RiskLevel,
            Instruction = "Observe and Report"
        };
    }
}

Step 6: SQL DbStrategy design explained

AIPatrolCamera uses strategy pattern for DB provider selection:

IDbProviderStrategy
PostgresDbProviderStrategy
SqliteDbProviderStrategy
DbProviderStrategyResolver

Program.cs registers both strategies and resolves one by config key:

"Database": {
  "Provider": "Postgres"
}

Why this DbStrategy is good:

No hardcoded provider in startup logic
Easy switching between PostgreSQL and SQLite
Good for local demo vs deployment environment
Keeps EF Core configuration clean and extensible

In this project, AppDbContext currently contains a People table with fields like:

Name
RiskLevel
FaceEmbedding (byte[] placeholder for model output)

This aligns with patrol use case and future AI model integration.

Detailed coding (`Data/DbStrategy/*`)

public interface IDbProviderStrategy
{
    string ProviderName { get; }
    void Configure(DbContextOptionsBuilder optionsBuilder, IConfiguration configuration);
}

public class PostgresDbProviderStrategy : IDbProviderStrategy
{
    public string ProviderName => "Postgres";

    public void Configure(DbContextOptionsBuilder optionsBuilder, IConfiguration configuration)
    {
        var connectionString = configuration.GetConnectionString("DefaultConnection")
            ?? throw new InvalidOperationException("ConnectionStrings:DefaultConnection is required for Postgres provider.");

        optionsBuilder.UseNpgsql(connectionString);
    }
}

public class SqliteDbProviderStrategy : IDbProviderStrategy
{
    public string ProviderName => "Sqlite";

    public void Configure(DbContextOptionsBuilder optionsBuilder, IConfiguration configuration)
    {
        var connectionString = configuration.GetConnectionString("SqliteConnection")
            ?? "Data Source=AIPatrolCamera.db";

        optionsBuilder.UseSqlite(connectionString);
    }
}

public class DbProviderStrategyResolver(IEnumerable<IDbProviderStrategy> strategies, IConfiguration configuration)
{
    public IDbProviderStrategy Resolve()
    {
        var configuredProvider = configuration["Database:Provider"] ?? "Postgres";

        var strategy = strategies.FirstOrDefault(s =>
            string.Equals(s.ProviderName, configuredProvider, StringComparison.OrdinalIgnoreCase));

        return strategy ?? throw new InvalidOperationException($"Unsupported Database:Provider '{configuredProvider}'.");
    }
}

And in Program.cs:

builder.Services.AddSingleton<IDbProviderStrategy, SqliteDbProviderStrategy>();
builder.Services.AddSingleton<IDbProviderStrategy, PostgresDbProviderStrategy>();
builder.Services.AddSingleton<DbProviderStrategyResolver>();
builder.Services.AddDbContext<AppDbContext>((serviceProvider, options) =>
{
    var strategyResolver = serviceProvider.GetRequiredService<DbProviderStrategyResolver>();
    var strategy = strategyResolver.Resolve();
    strategy.Configure(options, builder.Configuration);
});

Step 7: Running the App

Run the app:

dotnet run

What to do next - real image detection with ONNX in ML.NET

The next milestone is replacing demo logic in FaceRecognitionService with real model inference.

Target direction:

Add ONNX face detection/recognition model to project
Load model through ML.NET pipeline
Preprocess camera frame (resize/normalize/tensor conversion)
Run inference to get embedding or prediction scores
Compare with stored embeddings in database
Apply threshold for match decision
Return confidence + risk-based instruction

The project already references Microsoft.ML.OnnxRuntime, so you have a good starting point.

When this part is done, patrol mode becomes true AI detection instead of static demo output.

Detailed coding skeleton for next step (ONNX + ML.NET direction)

Use this as a reference implementation structure for your next article:

public class FaceRecognitionService(AppDbContext dbContext)
{
    public async Task<DetectResponse> DetectAsync(string imageData, CancellationToken cancellationToken)
    {
        var imageBytes = DecodeImage(imageData);
        if (imageBytes.Length == 0)
        {
            return new DetectResponse { Match = false };
        }

        // 1) preprocess image -> tensor
        // 2) run ONNX inference -> embedding
        // 3) compare embedding with dbContext.People FaceEmbedding
        // 4) pick best score above threshold

        var threshold = 0.80f;
        var bestMatch = await dbContext.People.AsNoTracking().FirstOrDefaultAsync(cancellationToken);

        if (bestMatch is null)
        {
            return new DetectResponse { Match = false };
        }

        return new DetectResponse
        {
            Match = true,
            Name = bestMatch.Name,
            RiskLevel = bestMatch.RiskLevel,
            Instruction = "Observe and Report"
        };
    }
}

This keeps your readers focused on architecture first, then model details in the next deep-dive post.

Conclusion

In this article, we focused on three core ideas:

How Blazor connects to a device camera through JavaScript interop
How the current face recognition flow works end-to-end in AIPatrolCamera
How SQL DbStrategy keeps database provider selection clean and flexible

And most importantly, we prepared a clear next step: move from demo service logic to real ONNX-based image detection with ML.NET.

If you already finished the previous CRUD tutorial, this is a strong bridge from data-driven Blazor apps to AI-enabled real-world scenarios.

No Template Fits? Generate Your Own Awesome DESIGN.md with .NET and Ollama

David Au Yeung — Fri, 29 May 2026 14:21:04 +0000

Introduction

I found that lots of excellent DESIGN.md examples are already available in this awesome repo:

https://github.com/VoltAgent/awesome-design-md

Light introduction: this repository is a curated collection of ready-to-use DESIGN.md files extracted from real websites, designed to help AI agents generate UI with better visual consistency.

Big credit to the maintainers and contributors of awesome-design-md for pushing this direction forward and making design-system knowledge easier to reuse.

That said, sometimes I want to build something not included in the repository. Especially when I am in an old-school mood and want a retro flavor that is uniquely mine. ;)

So in this tutorial, we build a fun experiment: a custom DESIGN.md generator app in C#.

The app will:

Crawl a target page.
Extract visual tokens (colors, fonts, semantic classes).
Ask LLM to synthesize a full DESIGN.md.
Ask LLM to generate a verification index.html from that DESIGN.md.
Save both files locally.

We will use:

.NET 8
OllamaSharp
http://localhost:11434
nemotron-3-super:cloud

What We Are Building

Target URL
  -> DesignMdGenerator.CrawlAndExtractMetadataAsync
  -> tokenized design metadata (title/colors/fonts/classes)
  -> Ollama (nemotron-3-super:cloud)
  -> DESIGN.md
  -> Ollama verification round
  -> index.html
  -> save to Output/DesignMdGenerator

Prerequisites

Visual Studio or VS Code
.NET 8 SDK
Ollama running locally
Model available in your Ollama environment

Run Ollama with the model used in this demo:

ollama run nemotron-3-super:cloud

If your Ollama service is already running at http://localhost:11434, you are good.

Step 1: Create a New Console App

dotnet new console -n DesignMdGeneratorDemo
cd DesignMdGeneratorDemo
dotnet add package OllamaSharp

Step 2: Project File (Reference)

Your .csproj should include at least:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="OllamaSharp" Version="5.4.25" />
  </ItemGroup>
</Project>

Step 3: Add `Program.cs`

This version is focused only on the DESIGN.md demo flow.

using DesignMdGeneratorDemo.Services;

Console.OutputEncoding = System.Text.Encoding.UTF8;

string targetUrl = args.Length > 0 ? args[0] : "https://www.yahoo.com";
string modelName = args.Length > 1 ? args[1] : "nemotron-3-super:cloud";
string ollamaApiUrl = args.Length > 2 ? args[2] : "http://localhost:11434";

var generator = new DesignMdGenerator(ollamaApiUrl, modelName);
var outputDirectory = Path.Combine(Directory.GetCurrentDirectory(), "Output", "DesignMdGenerator");

Console.WriteLine("Custom DESIGN.md Generator Demo");
Console.WriteLine("-------------------------------");
Console.WriteLine($"Target URL : {targetUrl}");
Console.WriteLine($"Model      : {modelName}");
Console.WriteLine($"Ollama URL : {ollamaApiUrl}");
Console.WriteLine();

var result = await generator.GenerateArtifactsAsync(targetUrl, outputDirectory);

Console.WriteLine("Generation complete.");
Console.WriteLine($"DESIGN.md : {result.DesignMarkdownPath}");
Console.WriteLine($"index.html: {result.VerificationHtmlPath}");

if (!string.IsNullOrWhiteSpace(result.WarningMessage))
{
    Console.WriteLine();
    Console.WriteLine("Warning:");
    Console.WriteLine(result.WarningMessage);
}

Step 4: Add `Services/DesignMdGenerator.cs`

Create Services folder, then add this complete service class:

using OllamaSharp;
using System.Net;
using System.Text;
using System.Text.RegularExpressions;

namespace DesignMdGeneratorDemo.Services;

public sealed class DesignMdGenerationResult
{
    public required string TargetUrl { get; init; }
    public required string DesignMarkdown { get; init; }
    public required string DesignMarkdownPath { get; init; }
    public required string VerificationHtml { get; init; }
    public required string VerificationHtmlPath { get; init; }
    public required DesignSiteMetadata Metadata { get; init; }
    public string? WarningMessage { get; init; }
}

public sealed class DesignSiteMetadata
{
    public string Title { get; init; } = string.Empty;
    public IReadOnlyList<string> Colors { get; init; } = [];
    public IReadOnlyList<string> Fonts { get; init; } = [];
    public IReadOnlyList<string> StructuralClasses { get; init; } = [];
    public IReadOnlyList<string> StylesheetUrls { get; init; } = [];
}

public sealed class DesignMdGenerator
{
    private static readonly Regex TitleRegex = new("<title[^>]*>(?<title>.*?)</title>", RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.Compiled);
    private static readonly Regex StyleBlockRegex = new("<style[^>]*>(?<style>.*?)</style>", RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.Compiled);
    private static readonly Regex InlineStyleRegex = new("style\\s*=\\s*[\"'](?<value>.*?)[\"']", RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.Compiled);
    private static readonly Regex StylesheetHrefRegex = new("<link[^>]*rel=[\"'][^\"']*stylesheet[^\"']*[\"'][^>]*href=[\"'](?<href>[^\"']+)[\"'][^>]*>", RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.Compiled);
    private static readonly Regex ClassRegex = new("class\\s*=\\s*[\"'](?<value>[^\"']+)[\"']", RegexOptions.IgnoreCase | RegexOptions.Singleline | RegexOptions.Compiled);
    private static readonly Regex HexColorRegex = new("#([0-9a-fA-F]{3,8})\\b", RegexOptions.Compiled);
    private static readonly Regex RgbColorRegex = new("rgba?\\(\\s*\\d+\\s*,\\s*\\d+\\s*,\\s*\\d+\\s*(?:,\\s*[0-9.]+\\s*)?\\)", RegexOptions.IgnoreCase | RegexOptions.Compiled);
    private static readonly Regex FontFamilyRegex = new("font-family\\s*:\\s*(?<value>[^;}]+)", RegexOptions.IgnoreCase | RegexOptions.Compiled);

    private static readonly string[] StructuralClassKeywords =
    [
        "btn", "button", "nav", "header", "footer", "card", "menu", "hero", "logo", "input"
    ];

    private readonly OllamaApiClient _ollamaClient;
    private readonly HttpClient _httpClient;
    private readonly string _ollamaApiUrl;
    private readonly string _modelName;

    public DesignMdGenerator(
        string ollamaApiUrl = "http://localhost:11434",
        string modelName = "nemotron-3-super:cloud",
        HttpClient? httpClient = null)
    {
        _ollamaApiUrl = ollamaApiUrl;
        _modelName = modelName;

        _ollamaClient = new OllamaApiClient(new Uri(ollamaApiUrl))
        {
            SelectedModel = modelName
        };

        _httpClient = httpClient ?? new HttpClient();
        if (_httpClient.DefaultRequestHeaders.UserAgent.Count == 0)
        {
            _httpClient.DefaultRequestHeaders.UserAgent.ParseAdd("Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36");
        }
    }

    public async Task<DesignMdGenerationResult> GenerateArtifactsAsync(
        string targetUrl,
        string? outputDirectory = null,
        CancellationToken cancellationToken = default)
    {
        if (string.IsNullOrWhiteSpace(targetUrl))
        {
            throw new ArgumentException("Target URL is required.", nameof(targetUrl));
        }

        targetUrl = NormalizeTargetUrl(targetUrl);

        outputDirectory = string.IsNullOrWhiteSpace(outputDirectory)
            ? Directory.GetCurrentDirectory()
            : outputDirectory;

        Directory.CreateDirectory(outputDirectory);

        var metadata = await CrawlAndExtractMetadataAsync(targetUrl, cancellationToken);
        var warnings = new List<string>();

        var designMarkdown = await GenerateDesignMarkdownAsync(metadata, targetUrl, warnings, cancellationToken);
        var designMarkdownPath = Path.Combine(outputDirectory, "DESIGN.md");
        await File.WriteAllTextAsync(designMarkdownPath, designMarkdown, cancellationToken);

        var verificationHtml = await GenerateVerificationHtmlAsync(designMarkdown, targetUrl, warnings, cancellationToken);
        var verificationHtmlPath = Path.Combine(outputDirectory, "index.html");
        await File.WriteAllTextAsync(verificationHtmlPath, verificationHtml, cancellationToken);

        return new DesignMdGenerationResult
        {
            TargetUrl = targetUrl,
            DesignMarkdown = designMarkdown,
            DesignMarkdownPath = designMarkdownPath,
            VerificationHtml = verificationHtml,
            VerificationHtmlPath = verificationHtmlPath,
            Metadata = metadata,
            WarningMessage = warnings.Count > 0 ? string.Join(Environment.NewLine, warnings) : null
        };
    }

    public async Task<string> GenerateDesignMarkdownAsync(
        DesignSiteMetadata metadata,
        string targetUrl,
        List<string>? warnings = null,
        CancellationToken cancellationToken = default)
    {
        var prompt = BuildDesignMarkdownPrompt(metadata, targetUrl);

        try
        {
            var markdown = await GenerateTextAsync(prompt, cancellationToken);
            return markdown.Trim();
        }
        catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.Forbidden)
        {
            warnings?.Add($"Ollama generation was forbidden (403) for model '{_modelName}' at '{_ollamaApiUrl}'. Generated heuristic DESIGN.md fallback instead.");
            return BuildFallbackDesignMarkdown(metadata, targetUrl);
        }
    }

    public async Task<string> GenerateVerificationHtmlAsync(
        string designMarkdown,
        string targetUrl,
        List<string>? warnings = null,
        CancellationToken cancellationToken = default)
    {
        if (string.IsNullOrWhiteSpace(designMarkdown))
        {
            throw new ArgumentException("Design markdown is required.", nameof(designMarkdown));
        }

        var prompt = BuildVerificationPrompt(designMarkdown, targetUrl);

        try
        {
            var rawHtml = await GenerateTextAsync(prompt, cancellationToken);
            return CleanModelCodeFence(rawHtml);
        }
        catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.Forbidden)
        {
            warnings?.Add($"Ollama HTML verification was forbidden (403) for model '{_modelName}'. Generated basic HTML fallback instead.");
            return BuildFallbackVerificationHtml(targetUrl);
        }
    }

    private async Task<string> GenerateTextAsync(string prompt, CancellationToken cancellationToken)
    {
        var builder = new StringBuilder();

        await foreach (var chunk in _ollamaClient.GenerateAsync(prompt, context: null, cancellationToken: cancellationToken))
        {
            if (!string.IsNullOrWhiteSpace(chunk?.Response))
            {
                builder.Append(chunk.Response);
            }
        }

        var response = builder.ToString();
        if (string.IsNullOrWhiteSpace(response))
        {
            throw new InvalidOperationException("The model response was empty.");
        }

        return response;
    }

    private static string BuildDesignMarkdownPrompt(DesignSiteMetadata metadata, string targetUrl)
    {
        return $$"""
You are a senior design-system analyst.

Analyze the extracted website design metadata and return a complete DESIGN.md document.
Output markdown only. No preface. No code fences.

Target URL: {{targetUrl}}
Page title: {{metadata.Title}}

Extracted colors:
- {{string.Join("\n- ", metadata.Colors.DefaultIfEmpty("n/a"))}}

Extracted fonts:
- {{string.Join("\n- ", metadata.Fonts.DefaultIfEmpty("n/a"))}}

Structural classes:
- {{string.Join("\n- ", metadata.StructuralClasses.DefaultIfEmpty("n/a"))}}

External stylesheets sampled:
- {{string.Join("\n- ", metadata.StylesheetUrls.DefaultIfEmpty("n/a"))}}

Required sections and order:
1. Overview
2. Colors (Brand & Accent, Surface, Text, Semantic)
3. Typography (Font Family, Hierarchy table, Principles)
4. Layout (Spacing System, Grid & Container, Whitespace Philosophy)
5. Elevation & Depth (table)
6. Shapes (Border Radius Scale table, Photography & Illustrations)
7. Components (Top Navigation, Buttons, Cards, Inputs, Badges, Tabs, Footer)
8. Do and Don't guidance
9. Responsive Behavior (Breakpoints table, Touch Targets, Collapsing Strategy)
10. Iteration Guide
11. Known Gaps

Keep it implementation-focused and concrete.
""";
    }

    private static string BuildVerificationPrompt(string designMarkdown, string targetUrl)
    {
        return $$"""
You are a senior front-end engineer validating a DESIGN.md spec.

Build a single-file index.html from DESIGN.md.
Return HTML only.

Target brand reference: {{targetUrl}}

DESIGN.md:
---
{{designMarkdown}}
---

Constraints:
- Use Tailwind CSS CDN.
- Include navigation, hero, content/feature section, and footer.
- Configure theme values to reflect DESIGN.md tokens.
- Keep layout responsive.
- Keep all code in one HTML file.
""";
    }

    private static string CleanModelCodeFence(string modelOutput)
    {
        if (string.IsNullOrWhiteSpace(modelOutput))
        {
            return string.Empty;
        }

        var cleaned = modelOutput.Trim();
        cleaned = Regex.Replace(cleaned, "^```
{% endraw %}
(?:html)?\\s*", string.Empty, RegexOptions.IgnoreCase);
        cleaned = Regex.Replace(cleaned, "\\s*
{% raw %}
```$", string.Empty, RegexOptions.IgnoreCase);
        return cleaned.Trim();
    }

    private async Task<DesignSiteMetadata> CrawlAndExtractMetadataAsync(string targetUrl, CancellationToken cancellationToken)
    {
        targetUrl = NormalizeTargetUrl(targetUrl);

        var pageUri = new Uri(targetUrl, UriKind.Absolute);
        var pageHtml = await _httpClient.GetStringAsync(pageUri, cancellationToken);

        var cssBuilder = new StringBuilder();

        foreach (Match styleMatch in StyleBlockRegex.Matches(pageHtml))
        {
            var css = styleMatch.Groups["style"].Value;
            if (!string.IsNullOrWhiteSpace(css))
            {
                cssBuilder.AppendLine(css);
            }
        }

        foreach (Match inlineStyleMatch in InlineStyleRegex.Matches(pageHtml))
        {
            var inlineStyle = WebUtility.HtmlDecode(inlineStyleMatch.Groups["value"].Value);
            if (!string.IsNullOrWhiteSpace(inlineStyle))
            {
                cssBuilder.AppendLine(inlineStyle);
            }
        }

        var stylesheetUrls = ExtractStylesheetUrls(pageHtml, pageUri, 3);
        foreach (var stylesheetUrl in stylesheetUrls)
        {
            try
            {
                var stylesheetContent = await _httpClient.GetStringAsync(stylesheetUrl, cancellationToken);
                if (!string.IsNullOrWhiteSpace(stylesheetContent))
                {
                    cssBuilder.AppendLine(stylesheetContent);
                }
            }
            catch
            {
                // Keep going on stylesheet fetch failures
            }
        }

        var rawCss = cssBuilder.ToString();

        return new DesignSiteMetadata
        {
            Title = ExtractTitle(pageHtml),
            Colors = ExtractUniqueColors(rawCss, 30),
            Fonts = ExtractUniqueFonts(rawCss, 12),
            StructuralClasses = ExtractStructuralClasses(pageHtml, 25),
            StylesheetUrls = stylesheetUrls
        };
    }

    private static string ExtractTitle(string html)
    {
        var titleMatch = TitleRegex.Match(html);
        if (!titleMatch.Success)
        {
            return "Unknown Title";
        }

        return WebUtility.HtmlDecode(titleMatch.Groups["title"].Value).Trim();
    }

    private static IReadOnlyList<string> ExtractStylesheetUrls(string html, Uri pageUri, int maxStylesheets)
    {
        var urls = new List<string>();
        var seen = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

        foreach (Match match in StylesheetHrefRegex.Matches(html))
        {
            if (urls.Count >= maxStylesheets)
            {
                break;
            }

            var href = WebUtility.HtmlDecode(match.Groups["href"].Value).Trim();
            if (string.IsNullOrWhiteSpace(href))
            {
                continue;
            }

            if (!Uri.TryCreate(pageUri, href, out var stylesheetUri))
            {
                continue;
            }

            var absoluteUrl = stylesheetUri.ToString();
            if (seen.Add(absoluteUrl))
            {
                urls.Add(absoluteUrl);
            }
        }

        return urls;
    }

    private static IReadOnlyList<string> ExtractUniqueColors(string css, int maxCount)
    {
        var colors = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

        foreach (Match hexMatch in HexColorRegex.Matches(css))
        {
            colors.Add(hexMatch.Value.ToLowerInvariant());
        }

        foreach (Match rgbMatch in RgbColorRegex.Matches(css))
        {
            colors.Add(rgbMatch.Value.ToLowerInvariant());
        }

        return colors.Take(maxCount).ToList();
    }

    private static IReadOnlyList<string> ExtractUniqueFonts(string css, int maxCount)
    {
        var fonts = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

        foreach (Match fontMatch in FontFamilyRegex.Matches(css))
        {
            var value = fontMatch.Groups["value"].Value
                .Replace("\"", string.Empty, StringComparison.Ordinal)
                .Replace("'", string.Empty, StringComparison.Ordinal)
                .Trim();

            if (!string.IsNullOrWhiteSpace(value))
            {
                fonts.Add(value);
            }
        }

        return fonts.Take(maxCount).ToList();
    }

    private static IReadOnlyList<string> ExtractStructuralClasses(string html, int maxCount)
    {
        var classes = new HashSet<string>(StringComparer.OrdinalIgnoreCase);

        foreach (Match classMatch in ClassRegex.Matches(html))
        {
            var classValue = classMatch.Groups["value"].Value;
            if (string.IsNullOrWhiteSpace(classValue))
            {
                continue;
            }

            foreach (var className in classValue.Split(' ', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries))
            {
                if (StructuralClassKeywords.Any(k => className.Contains(k, StringComparison.OrdinalIgnoreCase)))
                {
                    classes.Add(className);
                }
            }
        }

        return classes.Take(maxCount).ToList();
    }

    private static string NormalizeTargetUrl(string targetUrl)
    {
        var trimmed = targetUrl.Trim();

        if (Uri.TryCreate(trimmed, UriKind.Absolute, out var absoluteUri) &&
            (absoluteUri.Scheme == Uri.UriSchemeHttp || absoluteUri.Scheme == Uri.UriSchemeHttps))
        {
            return absoluteUri.ToString();
        }

        if (Uri.TryCreate($"https://{trimmed}", UriKind.Absolute, out var httpsUri))
        {
            return httpsUri.ToString();
        }

        throw new ArgumentException("Target URL must be a valid HTTP/HTTPS URL.", nameof(targetUrl));
    }

    private static string BuildFallbackDesignMarkdown(DesignSiteMetadata metadata, string targetUrl)
    {
        return $"""
# Overview
Heuristic fallback for {targetUrl}. LLM generation was not available.

## Colors
### Brand & Accent
- {string.Join("\n- ", metadata.Colors.Take(6).DefaultIfEmpty("n/a"))}

### Surface
- {metadata.Colors.Skip(6).FirstOrDefault() ?? "n/a"}

### Text
- {metadata.Colors.Skip(7).FirstOrDefault() ?? "n/a"}

### Semantic
- Success: #16a34a
- Warning: #f59e0b
- Error: #dc2626

## Typography
### Font Family
- {string.Join("\n- ", metadata.Fonts.DefaultIfEmpty("system-ui, sans-serif"))}

### Hierarchy
| Token | Size | Weight | Line Height | Letter Spacing | Use |
|---|---:|---:|---:|---:|---|
| h1 | 40px | 700 | 1.2 | -0.02em | Hero |
| h2 | 32px | 700 | 1.25 | -0.01em | Section heading |
| body | 16px | 400 | 1.6 | 0 | Paragraph |

### Principles
- Keep typography readable and consistent.

## Layout
### Spacing System
- 4, 8, 12, 16, 24, 32, 48

### Grid & Container
- Max-width: 1200px

### Whitespace Philosophy
- Favor breathable sections and clear grouping.

## Elevation & Depth
| Level | Treatment | Use |
|---|---|---|
| 0 | none | background |
| 1 | subtle shadow | cards |
| 2 | medium shadow | overlays |

## Shapes
### Border Radius Scale
| Token | Value | Use |
|---|---|---|
| sm | 6px | inputs |
| md | 10px | buttons |
| lg | 16px | cards |

### Photography & Illustrations
- Match page tone and avoid style drift.

## Components
- Top Navigation, Buttons, Cards, Inputs, Badges, Tabs, Footer with consistent spacing and state contrast.

## Do and Don't guidance
### Do
- Reuse tokens consistently.

### Don't
- Introduce random colors and font mixes.

## Responsive Behavior
### Breakpoints
| Name | Width | Key Changes |
|---|---|---|
| sm | 640px | stack compact groups |
| md | 768px | 2-column sections |
| lg | 1024px | wider content and nav |

### Touch Targets
- Minimum 44x44px.

### Collapsing Strategy
- Collapse nav and dense rows on small screens.

## Iteration Guide
1. Freeze token map.
2. Validate components.
3. Test breakpoints.

## Known Gaps
- Dynamic runtime interactions are not captured.
""";
    }

    private static string BuildFallbackVerificationHtml(string targetUrl)
    {
        var encodedTargetUrl = WebUtility.HtmlEncode(targetUrl);

        return $$"""
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>Design Preview</title>
  <style>
    :root { --bg:#0b1020; --card:#141a2e; --text:#e8ecff; --muted:#9aa3c7; --accent:#6ea8fe; }
    * { box-sizing: border-box; }
    body { margin:0; font-family: system-ui, -apple-system, Segoe UI, Roboto, sans-serif; background:var(--bg); color:var(--text); }
    .container { max-width:1100px; margin:0 auto; padding:24px; }
    .nav, .card { background:var(--card); border:1px solid #202948; border-radius:14px; }
    .nav { padding:14px 18px; display:flex; justify-content:space-between; align-items:center; }
    .hero { padding:56px 0 24px; }
    .btn { background:var(--accent); color:#071126; border:0; border-radius:10px; padding:10px 16px; font-weight:700; }
    .grid { display:grid; grid-template-columns:repeat(auto-fit, minmax(220px, 1fr)); gap:16px; margin-top:20px; }
    .card { padding:16px; }
    .muted { color:var(--muted); }
    footer { margin-top:28px; padding-top:18px; border-top:1px solid #202948; color:var(--muted); }
  </style>
</head>
<body>
  <div class="container">
    <div class="nav">
      <strong>Design Preview</strong>
      <span class="muted">{{encodedTargetUrl}}</span>
    </div>
    <section class="hero">
      <h1>Fallback verification page</h1>
      <p class="muted">Generated because LLM verification was unavailable.</p>
      <button class="btn">Primary Action</button>
    </section>
    <section class="grid">
      <article class="card"><h3>Card One</h3><p class="muted">Sample content block.</p></article>
      <article class="card"><h3>Card Two</h3><p class="muted">Sample content block.</p></article>
      <article class="card"><h3>Card Three</h3><p class="muted">Sample content block.</p></article>
    </section>
    <footer>Generated by DesignMdGenerator fallback renderer.</footer>
  </div>
</body>
</html>
""";
    }
}

Step 5: Run the Demo

dotnet run -- https://www.yahoo.com nemotron-3-super:cloud http://localhost:11434

If you want to test missing scheme URL normalization:

dotnet run -- yahoo.com nemotron-3-super:cloud http://localhost:11434

Step 6: Check Output

You should get:

Output/DesignMdGenerator/DESIGN.md
Output/DesignMdGenerator/index.html

Open index.html in browser to inspect if it aligns with the design spec generated from your target page.

Why This Is a Fun Experiment

You can quickly build custom design references for niche aesthetics.
You can compare generated DESIGN.md with existing public ones.
You can tune prompts to bias toward old-school, minimal, brutalist, or neon-retro tastes.
You can pair this workflow with your coding agent for faster UI iteration.

Notes and Limitations

Websites with heavy JavaScript rendering may require a headless browser pass.
Regex extraction is intentionally lightweight, not a full CSS parser.
Some cloud models may return 403 in specific environments; fallback mode in this service keeps the demo usable.

Credit

Again, credit to:

https://github.com/VoltAgent/awesome-design-md

This demo is inspired by the idea of making design intent explicit in markdown and applying it in AI-assisted UI workflows.

Closing

If you love unusual aesthetics like I do, this is a fun playground:

start from a URL,
generate a custom DESIGN.md,
let AI build the UI around your style.

Love C# & AI!

How AI Can Help You Recover Your Bitcoin

David Au Yeung — Sat, 16 May 2026 10:18:21 +0000

Introduction

When people talk about Artificial Intelligence today, the conversation usually revolves around chatbots, image generators, coding assistants, or office productivity.

But a recent news shared by Yahoo!Tech caught my attention for a very different reason.

According to the report, an X user known as cprkrn claimed that after being locked out of his Bitcoin wallet for 11 years, he finally recovered access with the help of Claude AI.

The wallet reportedly contained 5 BTC. Based on the approximate market price mentioned in the report, that was worth more than HKD 3 million.

The interesting part was not that AI "hacked Bitcoin".

It did not.

Instead, the user reportedly had:

An old computer
Old wallet files
Some forgotten notes
A seed phrase
A long-forgotten password pattern
Many years of messy digital history

AI helped connect the dots.

This is not a story about breaking cryptography.

It is a story about AI-assisted memory reconstruction.

And that opens up a powerful idea:

AI may not break encryption, but it can help us rediscover the human context around things we forgot.

This article explores:

How AI can reduce password search space
Why this is different from brute force cracking
How old notes can become useful signals
How to build a safe educational C# demo
How to use Ollama and Kimi as the LLM engine
Why privacy and ethics matter

Important:

This project is for education and simulation only.

It does not recover real Bitcoin wallets.

It does not parse real wallet.dat files.

It does not crack encryption.

It must not be used against anyone else’s accounts, wallets, devices, or data.

What Actually Happened Conceptually

The reported Bitcoin recovery story can be understood like this:

Old computer files
    ↓
Old wallet file discovered
    ↓
Old notes and memory fragments analyzed
    ↓
Possible password patterns reconstructed
    ↓
Seed phrase / wallet artifacts matched
    ↓
Wallet access recovered

The important distinction is this:

AI did not defeat Bitcoin cryptography.
AI helped organize messy human memory.

Bitcoin itself relies on strong cryptographic systems.

But humans often create passwords based on:

Emotions
Old events
Favorite words
Personal habits
Dates
Naming formats
Repeated patterns

That is where AI becomes useful.

Brute Force vs AI-Assisted Reasoning

A brute force approach looks like this:

Try every possible combination.
Try millions, billions, or trillions of passwords.
Hope one works.

This is expensive, slow, and usually unrealistic.

AI-assisted reasoning works differently.

Instead of attacking the encryption directly, it attacks the uncertainty around the human-created password.

It looks for clues such as:

Old notes
Diary fragments
File names
Repeated words
Emotional context
Important years
Formatting habits
Common personal patterns

So the workflow becomes:

Messy notes
    ↓
LLM analysis
    ↓
Ranked password candidates
    ↓
Local verification

That last step is important.

The LLM should generate candidates.

The actual verification should happen locally.

The Sample Exercise

For this article, we will create a safe simulation.

We will pretend that we found two old text files from an old computer:

old_notes.txt
diary_fragment.txt

These files contain clues.

The hidden mock password will be:

memory_police_2014

But in a real recovery situation, we would not know that.

The goal of the demo is to see whether an LLM can infer likely candidates from the notes.

Sample File 1: old_notes.txt

2014 - bought BTC when it was around 230 USD
Used police story as password theme before
Memory + river + sunset were words I liked back then
Laptop password had underscore format
Sometimes I append the year to important accounts

Sample File 2: diary_fragment.txt

Can't believe I finally bought Bitcoin.
Police documentary inspired me that week.
Maybe I should combine memory and police somehow.
Don't forget 2014 was important.

These notes are simple, but they contain strong human signals:

Clue	Possible Meaning
`memory`	likely password word
`police`	likely password word
`2014`	likely suffix
underscore format	likely separator
"combine memory and police"	likely word order
BTC price 230	possible alternative suffix

A human might miss the pattern.

An LLM can rank it immediately.

The Prompt We Give to the LLM

Here is the kind of prompt we will send to the model:

You are assisting in a password reconstruction exercise for a simulated wallet recovery.

This is an educational exercise using fake data.
The wallet is a local mock wallet owned by the user.

Your task:
1. Read the recovered historical notes.
2. Identify recurring words, themes, years, and formatting habits.
3. Generate 15 structured password candidates ranked by likelihood.
4. Prefer underscore separators if the notes suggest that style.
5. Consider important years or numbers as suffixes.
6. Do not brute force.
7. Do not generate random unrelated strings.
8. Return JSON only.

Recovered notes:

[old_notes.txt and diary_fragment.txt content here]

The key idea is:

Do not ask the model to crack anything.
Ask the model to reason from context.

Example LLM Result

In my test using Kimi through Ollama, the model generated a ranked candidate list similar to this:

Rank	Password Candidate	Rationale
1	`memory_police_2014`	Direct use of "combine memory and police" + underscore + year
2	`police_memory_2014`	Reverse order variation
3	`memory_river_sunset`	Uses three liked words
4	`police_story_2014`	Police story theme + year
5	`river_sunset_memory`	Alternative ordering of liked words
6	`memory_documentary_2014`	Memory + documentary clue
7	`memory_river_2014`	Liked word + year
8	`sunset_memory_2014`	Liked word + year
9	`police_river_2014`	Cross-combination
10	`river_memory_2014`	Alternative pair
11	`police_sunset_2014`	Cross-combination
12	`memory_2014`	Minimal pattern
13	`police_memory_230`	Uses BTC price clue
14	`memory_police_230`	Price-based variation
15	`sunset_river_2014`	Nature-themed pair + year

The important thing is not the exact output.

The important thing is that the model did not generate random strings like:

xJ9#qPz882!

Instead, it generated human-plausible candidates from the notes.

That is the value of AI here.

Demo Architecture

Our safe simulation looks like this:

old_notes.txt
diary_fragment.txt
        ↓
Ollama + Kimi model
        ↓
JSON password candidates
        ↓
Local mock wallet verifier
        ↓
Success / failure result

The LLM only sees the notes.

It does not receive:

A real wallet file
A private key
A seed phrase
A real password hash
A real Bitcoin address

The verification happens locally inside our C# program.

This is safer and cleaner

Technical Setup

This demo uses OllamaApiClient from OllamaSharp. OllamaSharp documents GenerateAsync for single-turn completions and the Chat class for conversational workflows; Ollama’s own API documentation also describes /api/generate and /api/chat streaming endpoints. (awaescher.github.io)

Create a new console app:

dotnet new console -n AiWalletRecoveryDemo
cd AiWalletRecoveryDemo
dotnet add package OllamaSharp

Make sure your Ollama endpoint is running at:

http://localhost:11434

The sample code defaults to:

string modelName = "kimi-k2.6:cloud";

If you used another model, such as kimi-k2.5, pass it as an argument:

dotnet run -- kimi-k2.5

Project Structure

AiWalletRecoveryDemo/
│
├── AiWalletRecoveryDemo.csproj
├── Program.cs
│
└── sample-data/
    ├── old_notes.txt
    ├── diary_fragment.txt
    └── mock_wallet.json

The program will create the sample files automatically if they do not exist.

Full Educational C# Example

Program.cs

using OllamaSharp;
using System.Security.Cryptography;
using System.Text;
using System.Text.Json;
using System.Text.Json.Serialization;
using System.Text.RegularExpressions;

internal static class Program
{
    // Educational only:
    // In a real recovery situation, you would NOT know this value.
    // We use it only to create a local mock wallet verifier.
    private const string DemoPassword = "memory_police_2014";

    public static async Task Main(string[] args)
    {
        Console.OutputEncoding = Encoding.UTF8;

        string modelName = args.Length > 0 ? args[0] : "kimi-k2.6:cloud";
        string ollamaApiUrl = args.Length > 1 ? args[1] : "http://localhost:11434";

        string dataDirectory = Path.Combine(Directory.GetCurrentDirectory(), "sample-data");
        string mockWalletPath = Path.Combine(dataDirectory, "mock_wallet.json");

        Console.WriteLine("AI-Assisted Wallet Recovery Simulation");
        Console.WriteLine("---------------------------------------");
        Console.WriteLine($"Ollama URL : {ollamaApiUrl}");
        Console.WriteLine($"Model      : {modelName}");
        Console.WriteLine();

        DemoData.EnsureCreated(dataDirectory, DemoPassword);

        string recoveredNotes = DemoData.ReadAllNotes(dataDirectory);
        var mockWallet = MockWalletVault.Load(mockWalletPath);

        var generator = new OllamaCandidateGenerator(
            ollamaApiUrl: ollamaApiUrl,
            modelName: modelName,
            wikiRootDirectory: dataDirectory);

        IReadOnlyList<PasswordCandidate> candidates;

        try
        {
            candidates = await generator.GenerateCandidatesAsync(recoveredNotes);
        }
        catch (Exception ex)
        {
            Console.WriteLine("LLM generation failed.");
            Console.WriteLine($"Reason: {ex.Message}");
            Console.WriteLine();
            Console.WriteLine("Using deterministic fallback candidates for demo continuity.");
            Console.WriteLine();

            candidates = FallbackCandidateGenerator.Generate();
        }

        var uniqueCandidates = candidates
            .Where(c => !string.IsNullOrWhiteSpace(c.Password))
            .Select(c => c with { Password = c.Password.Trim() })
            .GroupBy(c => c.Password, StringComparer.Ordinal)
            .Select((g, index) => g.First() with { Rank = index + 1 })
            .Take(25)
            .ToList();

        Console.WriteLine("Ranked Password Candidates");
        Console.WriteLine("--------------------------");

        foreach (var candidate in uniqueCandidates)
        {
            Console.WriteLine($"#{candidate.Rank}: {candidate.Password}");
            Console.WriteLine($"    Reason: {candidate.Rationale}");
        }

        Console.WriteLine();
        Console.WriteLine("Testing candidates against local mock wallet...");
        Console.WriteLine();

        PasswordCandidate? successfulCandidate = null;

        foreach (var candidate in uniqueCandidates)
        {
            bool isMatch = mockWallet.Verify(candidate.Password);

            if (isMatch)
            {
                successfulCandidate = candidate;
                break;
            }
        }

        if (successfulCandidate is not null)
        {
            Console.WriteLine($"✅ Mock wallet unlocked with candidate #{successfulCandidate.Rank}:");
            Console.WriteLine(successfulCandidate.Password);
        }
        else
        {
            Console.WriteLine("❌ No candidate unlocked the mock wallet.");
            Console.WriteLine("Try adding more historical notes or stronger clues.");
        }

        Console.WriteLine();
        Console.WriteLine("Simulation complete.");
    }
}

public sealed class OllamaCandidateGenerator
{
    private readonly OllamaApiClient _ollamaClient;
    private readonly string _wikiRootDirectory;

    public OllamaCandidateGenerator(
        string ollamaApiUrl = "http://localhost:11434",
        string modelName = "kimi-k2.6:cloud",
        string? wikiRootDirectory = null)
    {
        _ollamaClient = new OllamaApiClient(new Uri(ollamaApiUrl))
        {
            SelectedModel = modelName
        };

        _wikiRootDirectory = wikiRootDirectory ?? Directory.GetCurrentDirectory();
    }

    public async Task<IReadOnlyList<PasswordCandidate>> GenerateCandidatesAsync(
        string recoveredNotes,
        CancellationToken cancellationToken = default)
    {
        string prompt = BuildPrompt(recoveredNotes);

        var responseBuilder = new StringBuilder();

        await foreach (var stream in _ollamaClient.GenerateAsync(
            prompt,
            context: null,
            cancellationToken: cancellationToken))
        {
            if (!string.IsNullOrEmpty(stream?.Response))
            {
                responseBuilder.Append(stream.Response);
            }
        }

        string rawResponse = responseBuilder.ToString();

        var candidates = ParseCandidates(rawResponse);

        if (candidates.Count == 0)
        {
            throw new InvalidOperationException(
                "The model did not return valid password candidates.");
        }

        return candidates;
    }

    private string BuildPrompt(string recoveredNotes)
    {
        return $$"""
            You are assisting in a password reconstruction exercise for a simulated wallet recovery.

            This is an educational exercise using fake data.
            The mock wallet belongs to the user.
            Do not provide hacking instructions.
            Do not suggest brute force tools.
            Do not suggest unauthorized access.
            Do not generate random unrelated strings.

            Your task:
            1. Read the recovered historical notes.
            2. Identify recurring words, themes, dates, numbers, and formatting habits.
            3. Generate exactly 15 structured password candidates ranked by likelihood.
            4. Prefer underscore separators if the notes suggest that style.
            5. Consider important years or numbers as suffixes.
            6. Prefer candidates that follow explicit diary wording.
            7. Return valid JSON only.
            8. Do not wrap the JSON in Markdown.

            Return this JSON shape:

            {
              "candidates": [
                {
                  "rank": 1,
                  "password": "example_candidate",
                  "rationale": "Short explanation"
                }
              ]
            }

            Recovered notes:

            {{recoveredNotes}}
        """;
    }

    private static IReadOnlyList<PasswordCandidate> ParseCandidates(string rawResponse)
    {
        string json = ExtractJsonObject(rawResponse);

        var options = new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true
        };

        var parsed = JsonSerializer.Deserialize<CandidateResponse>(json, options);

        return parsed?.Candidates?
            .OrderBy(c => c.Rank)
            .ToList()
            ?? new List<PasswordCandidate>();
    }

    private static string ExtractJsonObject(string text)
    {
        string cleaned = text.Trim();

        cleaned = Regex.Replace(
            cleaned,
            "^```
{% endraw %}
(?:json)?\\s*",
            "",
            RegexOptions.IgnoreCase);

        cleaned = Regex.Replace(
            cleaned,
            "\\s*
{% raw %}
```$",
            "",
            RegexOptions.IgnoreCase);

        int start = cleaned.IndexOf('{');
        int end = cleaned.LastIndexOf('}');

        if (start < 0 || end <= start)
        {
            throw new FormatException("No JSON object found in model response.");
        }

        return cleaned.Substring(start, end - start + 1);
    }
}

public sealed record PasswordCandidate
{
    [JsonPropertyName("rank")]
    public int Rank { get; init; }

    [JsonPropertyName("password")]
    public string Password { get; init; } = "";

    [JsonPropertyName("rationale")]
    public string Rationale { get; init; } = "";
}

public sealed class CandidateResponse
{
    [JsonPropertyName("candidates")]
    public List<PasswordCandidate> Candidates { get; set; } = new();
}

public sealed class MockWalletVault
{
    private static readonly JsonSerializerOptions JsonOptions = new()
    {
        WriteIndented = true,
        PropertyNameCaseInsensitive = true
    };

    [JsonPropertyName("description")]
    public string Description { get; set; } = "Educational mock wallet. This is not a real Bitcoin wallet.";

    [JsonPropertyName("saltBase64")]
    public string SaltBase64 { get; set; } = "";

    [JsonPropertyName("passwordHashBase64")]
    public string PasswordHashBase64 { get; set; } = "";

    public static MockWalletVault CreateFromPassword(string password)
    {
        byte[] salt = RandomNumberGenerator.GetBytes(16);
        byte[] hash = HashPassword(password, salt);

        return new MockWalletVault
        {
            SaltBase64 = Convert.ToBase64String(salt),
            PasswordHashBase64 = Convert.ToBase64String(hash)
        };
    }

    public static MockWalletVault Load(string path)
    {
        string json = File.ReadAllText(path);

        return JsonSerializer.Deserialize<MockWalletVault>(json, JsonOptions)
            ?? throw new InvalidOperationException("Unable to load mock wallet.");
    }

    public void Save(string path)
    {
        string json = JsonSerializer.Serialize(this, JsonOptions);
        File.WriteAllText(path, json);
    }

    public bool Verify(string candidatePassword)
    {
        byte[] salt = Convert.FromBase64String(SaltBase64);
        byte[] expectedHash = Convert.FromBase64String(PasswordHashBase64);
        byte[] actualHash = HashPassword(candidatePassword, salt);

        return CryptographicOperations.FixedTimeEquals(actualHash, expectedHash);
    }

    private static byte[] HashPassword(string password, byte[] salt)
    {
        // Educational local verifier.
        // This is not Bitcoin Core wallet encryption.
        using var pbkdf2 = new Rfc2898DeriveBytes(
            password,
            salt,
            iterations: 100_000,
            hashAlgorithm: HashAlgorithmName.SHA256);

        return pbkdf2.GetBytes(32);
    }
}

public static class DemoData
{
    private const string OldNotesFileName = "old_notes.txt";
    private const string DiaryFileName = "diary_fragment.txt";
    private const string MockWalletFileName = "mock_wallet.json";

    private const string OldNotesText = """
    2014 - bought BTC when it was around 230 USD
    Used police story as password theme before
    Memory + river + sunset were words I liked back then
    Laptop password had underscore format
    Sometimes I append the year to important accounts
    """;

    private const string DiaryFragmentText = """
    Can't believe I finally bought Bitcoin.
    Police documentary inspired me that week.
    Maybe I should combine memory and police somehow.
    Don't forget 2014 was important.
    """;

    public static void EnsureCreated(string dataDirectory, string demoPassword)
    {
        Directory.CreateDirectory(dataDirectory);

        string oldNotesPath = Path.Combine(dataDirectory, OldNotesFileName);
        string diaryPath = Path.Combine(dataDirectory, DiaryFileName);
        string mockWalletPath = Path.Combine(dataDirectory, MockWalletFileName);

        if (!File.Exists(oldNotesPath))
        {
            File.WriteAllText(oldNotesPath, OldNotesText);
        }

        if (!File.Exists(diaryPath))
        {
            File.WriteAllText(diaryPath, DiaryFragmentText);
        }

        if (!File.Exists(mockWalletPath))
        {
            var wallet = MockWalletVault.CreateFromPassword(demoPassword);
            wallet.Save(mockWalletPath);
        }
    }

    public static string ReadAllNotes(string dataDirectory)
    {
        var builder = new StringBuilder();

        foreach (string file in Directory
            .EnumerateFiles(dataDirectory, "*.txt", SearchOption.AllDirectories)
            .OrderBy(f => f))
        {
            builder.AppendLine($"--- {Path.GetFileName(file)} ---");
            builder.AppendLine(File.ReadAllText(file));
            builder.AppendLine();
        }

        return builder.ToString();
    }
}

public static class FallbackCandidateGenerator
{
    public static IReadOnlyList<PasswordCandidate> Generate()
    {
        return new List<PasswordCandidate>
        {
            new()
            {
                Rank = 1,
                Password = "memory_police_2014",
                Rationale = "Direct implementation of diary note: combine memory and police, underscore format, year suffix."
            },
            new()
            {
                Rank = 2,
                Password = "police_memory_2014",
                Rationale = "Reverse order variation using the same strong clues."
            },
            new()
            {
                Rank = 3,
                Password = "memory_river_sunset",
                Rationale = "Uses three liked words with underscore formatting."
            },
            new()
            {
                Rank = 4,
                Password = "police_story_2014",
                Rationale = "References previous police story theme and important year."
            },
            new()
            {
                Rank = 5,
                Password = "river_sunset_memory",
                Rationale = "Alternative ordering of liked words."
            },
            new()
            {
                Rank = 6,
                Password = "memory_documentary_2014",
                Rationale = "Combines memory with police documentary clue and year."
            },
            new()
            {
                Rank = 7,
                Password = "memory_river_2014",
                Rationale = "Liked word pair plus year suffix."
            },
            new()
            {
                Rank = 8,
                Password = "sunset_memory_2014",
                Rationale = "Liked word combination plus year."
            },
            new()
            {
                Rank = 9,
                Password = "police_river_2014",
                Rationale = "Cross-combination of police theme, liked word, and year."
            },
            new()
            {
                Rank = 10,
                Password = "river_memory_2014",
                Rationale = "Alternative liked word pair plus year."
            },
            new()
            {
                Rank = 11,
                Password = "police_sunset_2014",
                Rationale = "Cross-combination of police theme, liked word, and year."
            },
            new()
            {
                Rank = 12,
                Password = "memory_2014",
                Rationale = "Minimal pattern using important word and year."
            },
            new()
            {
                Rank = 13,
                Password = "police_memory_230",
                Rationale = "Uses BTC price clue instead of year."
            },
            new()
            {
                Rank = 14,
                Password = "memory_police_230",
                Rationale = "Price-based variation of the strongest phrase."
            },
            new()
            {
                Rank = 15,
                Password = "sunset_river_2014",
                Rationale = "Nature-themed pair plus year suffix."
            }
        };
    }
}

Example Output

Your result may vary depending on the model, but a successful run may look like this:

This is exactly the concept we want to demonstrate.

The model does not break encryption.

It simply turns messy personal history into a ranked list of likely hypotheses.

What AI Actually Contributes

The difference between brute force and AI reasoning is not magic.

It is context.

Brute force says:

Try everything.

AI-assisted reasoning says:

Try what the human was most likely to create.

In this exercise, the LLM extracted:

Signal	Extracted Insight
`memory`	important word
`police`	important theme
`combine memory and police`	likely word pairing
underscore format	separator style
`2014`	likely suffix
BTC price `230`	alternative numeric suffix
diary wording	word order clue

This changes the search problem from:

Trillions of random guesses

to:

15 structured candidates

That is the power.

AI reduces chaos.

Why This Is Not "AI Cracking Bitcoin"

This point is very important.

Bitcoin was not broken.

Cryptography was not defeated.

The AI did not discover a private key from the blockchain.

The AI did not reverse SHA-256.

The AI did not bypass wallet encryption.

Instead, the AI helped with:

Pattern recognition
File interpretation
Note summarization
Candidate ranking
Human memory reconstruction

That is a completely different category.

A good analogy is this:

Encryption is the locked safe.
AI helps you search your old notebooks for the combination.

The safe is still strong.

The weakness is human memory.

Privacy Warning

This is where we need to be careful.

If you use a cloud model, do not upload:

Real seed phrases
Private keys
Real wallet files
Password databases
Full disk images
Sensitive personal documents

Even if your intention is legitimate, sending secrets to a cloud model can create serious privacy risk.

A safer workflow is:

Sensitive file stays local
    ↓
You extract non-secret clues
    ↓
LLM generates candidate ideas
    ↓
Verification happens locally

For example, instead of sending this:

seed phrase: apple apple apple ...
wallet.dat file attached

Send only sanitized hints like:

I often used words related to memory, police, river, and 2014.
I used underscores in passwords at that time.

The LLM should help with reasoning.

It should not become a place where secrets are stored.

How This Pattern Applies Beyond Bitcoin

This same AI-assisted recovery pattern can apply to many areas:

Old encrypted ZIP archives
Forgotten developer keystores
Legacy configuration files
Personal knowledge archives
Digital estate planning
Old project recovery
Family photo backup restoration
Enterprise documentation reconstruction

The common pattern is:

Messy historical data
    ↓
AI-assisted organization
    ↓
Ranked hypotheses
    ↓
Local verification

This is why I find the story so interesting.

It shows AI being used not as a chatbot, but as a digital archaeologist.

Security Lessons

There is also a defensive lesson here.

If AI can infer human password patterns from old notes, then we should avoid creating passwords from personal context.

Better practices:

Use a password manager
Use long random passwords
Avoid emotional or memorable phrases
Avoid years, birthdays, and repeated themes
Do not store seed phrases digitally
Use hardware wallets for serious crypto storage
Keep offline backups in physically secure locations
Separate password hints from actual recovery material

Human-style passwords are easy to remember.

That is exactly why they can be guessed.

Conclusion

The reported Bitcoin recovery story is not about AI defeating cryptography.

It is about AI helping a person reconstruct forgotten context.

That may become one of AI's most underrated uses.

Not replacing humans.

Not magically solving everything.

But helping us search, organize, and reason through the complexity we created over years of digital life.

In this demo, we used:

Old notes
A diary fragment
Ollama
Kimi
C#
A local mock wallet verifier

And we simulated the same core idea safely:

Forgotten memory → AI reasoning → candidate ranking → local verification

The future of AI may not only be automation.

It may also be recovery.

Recovering old knowledge.

Recovering lost context.

Recovering forgotten work.

Recovering what we once knew but could no longer find.

AI did not break the lock.

It helped us remember where we left the key.

References

OllamaSharp documentation for GenerateAsync, Chat, and OllamaApiClient. (awaescher.github.io)
Ollama API documentation for /api/generate and /api/chat. (github.com)

Love C# & AI!

Forget Your RAG: Build Your Own LLM Wiki in C# with Ollama + Kimi (Step‑by‑Step Guide)

David Au Yeung — Wed, 06 May 2026 09:11:14 +0000

Introduction

Happy coding! Today I want to share a practical AI tutorial in .NET style, with real code, simple architecture, and a result you can run on your own machine.

When many developers start building AI knowledge assistants, the first idea is usually RAG. That is a good choice in many cases, but not always the simplest one. Sometimes, your knowledge base is actually small, focused, and stable. In that lovely situation, building a small LLM Wiki can be a more elegant choice.

Let me tell a short lovely story.

Imagine a small tea house run by a kind grandmother. Every morning, her grandchildren ask the same questions:

Which tea is good for a cold day?
Which dessert has nuts?
What is the house special today?

Now imagine two ways to help them.

The first way is to hire a fast librarian who runs to a giant archive room every time a child asks a question. That is a bit like RAG.
The second way is to write one beautiful, well-organized family handbook and keep it on the table all the time. That is a bit like an LLM Wiki.

If the tea house menu is small and stable, the handbook is often faster, simpler, and more reliable. But if the tea house becomes a huge restaurant chain with thousands of daily updates, you will eventually want the librarian too.

That is the heart of LLM Wiki vs RAG.

In this tutorial, we will build an open-source local LLM Wiki demo in C# using:

.NET 8
Ollama
OllamaSharp
a local markdown-based wiki structure
the kimi-k2.6:cloud Ollama model

By the end, you will have:

a console-based demo app
a LocalWiki folder with markdown files
document ingestion logic
index maintenance logic
wiki question-answering logic
a clear understanding of when to use a wiki instead of RAG

What We Are Building

We are building a small local AI workflow like this:

Prepare a source document.
Send that document to an LLM through Ollama.
Ask the LLM to return structured wiki content.
Save the result as markdown in a local wiki folder.
Update Index.md automatically.
Ask questions against the wiki content.
Let the model answer using the wiki instead of the raw source file.

This is not a full vector database pipeline. It is intentionally lighter.

LLM Wiki vs RAG

Before we code, let us understand the design choice.

What is RAG?

Retrieval-Augmented Generation (RAG) improves LLM output by retrieving relevant information from external sources before generating a response. Instead of depending only on training data, the model gets fresh context from documents, databases, or web content.

Common characteristics of RAG:

dynamic retrieval at question time
usually based on chunking + embeddings + vector search
good for large and changing knowledge bases
better for source attribution and enterprise-scale search
more infrastructure and tuning effort

What is an LLM Wiki?

An LLM Wiki is a curated, structured markdown knowledge base written so the model can reason over it directly. Rather than retrieving many chunks at runtime, you keep important domain knowledge in concise markdown files and pass those files into the model context.

Common characteristics of an LLM Wiki:

markdown-first knowledge organization
compact, human-readable, and model-friendly
great for small and stable domains
simple to maintain for focused use cases
low setup cost compared with a full RAG pipeline

When should you use a Wiki instead of RAG?

A wiki is a strong choice when:

your knowledge base is relatively small
your content changes slowly
you want to ship fast
you prefer markdown and file-based maintenance
you want fewer moving parts
you are building a demo, prototype, internal assistant, or focused domain tool

RAG is usually better when:

you have a very large knowledge base
documents change frequently
you need deep retrieval across many domains
you need richer source attribution and search behavior
your content does not fit comfortably into context

A practical rule of thumb

Start with an LLM Wiki if your knowledge is:

focused
stable
not too large
curated by humans or AI into clean markdown

Move to RAG when your knowledge becomes:

too large
too dynamic
too fragmented
too cross-domain

And yes, a hybrid approach is often best:

use a wiki for stable core knowledge
use RAG for large or fast-changing content

References and background reading

The ideas in this tutorial align with public explanations of RAG and LLM Wiki tradeoffs, including:

Wikipedia on Retrieval-Augmented Generation
AWS explanation of RAG and external knowledge grounding
MindStudio and 99helpers comparisons of LLM Wiki vs RAG for smaller knowledge bases

Prerequisites

Before we begin, make sure you have the following:

Visual Studio or another C# IDE
.NET 8 SDK
Ollama installed locally
the Kimi model available through Ollama
a Windows terminal or PowerShell

To use the model from this demo, run:

ollama run kimi-k2.6:cloud

If Ollama is already running, that is enough for the demo.

Step 1: Create the Console App

If you want to build this from scratch in a new workspace, start with:

dotnet new console -n LLMWikiDemo
cd LLMWikiDemo

In this project, the feature was added into an existing .NET 8 console app, but the same idea applies to a fresh app.

Step 2: Add the NuGet Package

Add OllamaSharp so your C# application can talk to Ollama:

dotnet add package OllamaSharp

In this workspace, the project file already contains:

<PackageReference Include="OllamaSharp" Version="5.4.25" />

Step 3: Define the Architecture

To keep the system architecture simple, we use these parts:

Program.cs as the entry point
LlmWikiManager.cs as the core service
LocalWiki/ as the generated markdown wiki
SCHEMA.md to define the wiki rules
Index.md as the article catalog
Articles/ for wiki pages

The flow is:

Source Document
    -> LlmWikiManager.IngestDocumentAsync(...)
    -> Ollama / Kimi model
    -> JSON-like structured response
    -> Markdown article
    -> Index.md update
    -> QueryWikiAsync(...)
    -> Answer from wiki context

Step 4: Create the Wiki Manager

The main logic lives in Utils/LLMWikiManager.cs.

This class is responsible for:

creating the wiki folders
creating SCHEMA.md and Index.md
sending prompts to Ollama
parsing the model response
writing article markdown
reading article markdown back for Q&A

The manager constructor

We configure the Ollama endpoint and default model here:

public LlmWikiManager(
    string ollamaApiUrl = "http://localhost:11434",
    string modelName = "kimi-k2.6:cloud",
    string? wikiRootDirectory = null)
{
    _ollamaClient = new OllamaApiClient(new Uri(ollamaApiUrl))
    {
        SelectedModel = modelName
    };

    _wikiDirectory = wikiRootDirectory ?? Path.Combine(AppContext.BaseDirectory, "LocalWiki");
    _schemaFilePath = Path.Combine(_wikiDirectory, "SCHEMA.md");
    _indexFilePath = Path.Combine(_wikiDirectory, "Index.md");
    _articlesDirectory = Path.Combine(_wikiDirectory, "Articles");
}

This means the wiki is generated near the app runtime folder, and the model defaults to kimi-k2.6:cloud.

Step 5: Bootstrap the Wiki Structure

We want the app to create the wiki structure automatically if it does not exist.

public async Task EnsureWikiStructureAsync()
{
    Directory.CreateDirectory(_wikiDirectory);
    Directory.CreateDirectory(_articlesDirectory);

    if (!File.Exists(_schemaFilePath))
    {
        await File.WriteAllTextAsync(_schemaFilePath, DefaultSchema);
    }

    if (!File.Exists(_indexFilePath))
    {
        var initialIndex = "# Local Wiki Index" + Environment.NewLine + Environment.NewLine;
        await File.WriteAllTextAsync(_indexFilePath, initialIndex);
    }
}

This is one of the reasons the wiki approach feels nice. It is file-based, easy to inspect, and easy to explain.

Step 6: Stream Text from Ollama

OllamaSharp returns generation results as an async stream, so we collect the response text like this:

private async Task<string> GenerateTextAsync(string prompt)
{
    var builder = new StringBuilder();

    await foreach (var chunk in _ollamaClient.GenerateAsync(prompt))
    {
        if (!string.IsNullOrWhiteSpace(chunk?.Response))
        {
            builder.Append(chunk.Response);
        }
    }

    return builder.ToString();
}

This is a small but important detail. If you try to await the sequence directly, the build will fail. You must use await foreach.

Step 7: Ingest a Source Document

Now comes the most interesting part.

When a source document arrives, we:

read the file
read the schema
ask the model to return structured wiki data
parse the result
create a markdown article
update Index.md

The ingestion prompt

The ingestion prompt in LlmWikiManager.cs looks like this:

var ingestionPrompt = $"""
    You are an AI assistant maintaining a markdown wiki.

    Schema:
    ---
    {schemaContent}
    ---

    Process this source document and respond with ONLY one JSON object using these keys:
    - summaryTitle: concise title for the article
    - summaryFilename: kebab-case markdown filename
    - summaryContent: full markdown article body
    - indexUpdate: one markdown bullet linking article from Index.md

    Source filename: {sourceFileName}
    Source document:
    ---
    {sourceContent}
    ---
 """;

This is a practical pattern:

tell the model who it is
give it the wiki rules
give it the source content
enforce a structured output format

The ingestion method

A simplified view of the ingestion code:

public async Task<LlmWikiIngestionResult> IngestDocumentAsync(string sourceFilePath)
{
    await EnsureWikiStructureAsync();

    var sourceContent = await File.ReadAllTextAsync(sourceFilePath);
    var schemaContent = await File.ReadAllTextAsync(_schemaFilePath);
    var sourceFileName = Path.GetFileName(sourceFilePath);

    var responseText = await GenerateTextAsync(ingestionPrompt);
    var parsed = TryParseIngestionPayload(responseText);

    var summaryTitle = !string.IsNullOrWhiteSpace(parsed?.SummaryTitle)
        ? parsed!.SummaryTitle!
        : $"Summary of {Path.GetFileNameWithoutExtension(sourceFileName)}";

    var summaryFilename = NormalizeSummaryFilename(parsed?.SummaryFilename ?? string.Empty, summaryTitle);

    var summaryContent = !string.IsNullOrWhiteSpace(parsed?.SummaryContent)
        ? parsed!.SummaryContent!
        : BuildFallbackSummaryContent(sourceFileName, sourceContent);

    var summaryFilePath = Path.Combine(_articlesDirectory, summaryFilename);
    await File.WriteAllTextAsync(summaryFilePath, summaryContent);

    var normalizedRelativeArticlePath = $"Articles/{summaryFilename}";
    var indexUpdate = !string.IsNullOrWhiteSpace(parsed?.IndexUpdate)
        ? parsed!.IndexUpdate!.Trim()
        : $"- [{summaryTitle}]({normalizedRelativeArticlePath})";

    // append to Index.md if needed
}

Why fallback logic matters

Real LLMs are helpful, but sometimes they do not follow the JSON contract perfectly.

That is why the demo includes:

JSON extraction from mixed text
deserialization attempts
fallback summary generation
filename normalization
index deduplication

This makes the POC stronger and more production-minded than a fragile one-shot prompt demo.

Step 8: Parse the LLM Response Safely

Structured AI output is never perfect, so the code extracts the JSON object defensively.

private static string? ExtractJsonObject(string text)
{
    if (string.IsNullOrWhiteSpace(text))
    {
        return null;
    }

    var start = text.IndexOf('{');
    var end = text.LastIndexOf('}');

    if (start < 0 || end <= start)
    {
        return null;
    }

    return text[start..(end + 1)];
}

Then we try to deserialize it:

private static LlmWikiIngestionPayload? TryParseIngestionPayload(string responseText)
{
    var rawJson = ExtractJsonObject(responseText);
    if (rawJson is null)
    {
        return null;
    }

    try
    {
        return JsonSerializer.Deserialize<LlmWikiIngestionPayload>(rawJson, new JsonSerializerOptions
        {
            PropertyNameCaseInsensitive = true
        });
    }
    catch
    {
        return null;
    }
}

This is a great lesson for readers: LLM output should be handled like user input. Trust it carefully, never blindly.

Step 9: Query the Wiki

Once the wiki exists, we can query it.

The app reads:

SCHEMA.md
Index.md
the latest markdown articles

Then it builds a prompt for the model.

public async Task<string> QueryWikiAsync(string question)
{
    await EnsureWikiStructureAsync();

    var schemaContent = await File.ReadAllTextAsync(_schemaFilePath);
    var indexContent = await File.ReadAllTextAsync(_indexFilePath);
    var articleContext = await BuildArticleContextAsync(maxArticles: 6, maxCharsPerArticle: 2400);

    var queryPrompt = $"""
        You are an AI assistant answering questions from a local markdown wiki.

        Rules:
        - Use only the provided wiki context.
        - If information is insufficient, explicitly say so.
        - Keep response concise.
        - Cite article filenames used as sources.

        Schema:
        ---
        {schemaContent}
        ---

        Index:
        ---
        {indexContent}
        ---

        Article context:
        ---
        {articleContext}
        ---

        Question: {question}
     """;

    var answer = (await GenerateTextAsync(queryPrompt)).Trim();

    if (string.IsNullOrWhiteSpace(answer))
    {
        return "Insufficient information in the wiki context to answer this question.";
    }

    return answer;
}

This is a wiki-style answer flow, not a vector retrieval flow.

Step 10: Wire Everything in Program.cs

The entry point demonstrates the entire POC.

using MyPlaygroundApp.Utils;

class Program
{
    static async Task Main(string[] args)
    {
        Console.WriteLine("Open-Source LLM Wiki Demo (.NET + Ollama)");
        Console.WriteLine("------------------------------------------");
        Console.WriteLine();

        var wikiManager = new LlmWikiManager(modelName: "kimi-k2.6:cloud");
        await wikiManager.EnsureWikiStructureAsync();

        var demoInputDirectory = Path.Combine(AppContext.BaseDirectory, "DemoInput");
        Directory.CreateDirectory(demoInputDirectory);

        var sourceDocumentPath = Path.Combine(demoInputDirectory, "csharp-ai-benefits.txt");
        var sourceDocumentContent = """
            C# is effective for AI solution development due to strong typing, mature tooling, and excellent package management.
            The .NET ecosystem enables production-ready services, background workers, APIs, and cloud integration.
            Developers can integrate local LLMs using Ollama and open-source libraries such as OllamaSharp and Semantic Kernel.
            This approach is useful for private knowledge workflows like a local markdown wiki with ingestion and Q&A.
        """;

        await File.WriteAllTextAsync(sourceDocumentPath, sourceDocumentContent);

        Console.WriteLine("Ingesting source document into local wiki...");
        var ingestionResult = await wikiManager.IngestDocumentAsync(sourceDocumentPath);
        Console.WriteLine($"Article created: {ingestionResult.SummaryFilename}");
        Console.WriteLine($"Wiki location: {wikiManager.WikiDirectory}");
        Console.WriteLine();

        const string question = "What are the benefits of using C# for local LLM wiki development?";
        Console.WriteLine($"Question: {question}");
        var answer = await wikiManager.QueryWikiAsync(question);
        Console.WriteLine();
        Console.WriteLine("Answer:");
        Console.WriteLine(answer);

        Console.WriteLine();
        Console.WriteLine("Demo complete.");
    }
}

This is excellent for a tutorial because readers can run it and immediately see the full loop.

Step 11: Run the Demo

From the solution root, run:

dotnet run --project .\MyPlaygroundApp\MyPlaygroundApp.csproj

If Ollama is available and kimi-k2.6:cloud is usable, the demo should:

create the wiki structure
ingest the sample source document
write a markdown article
update the index
answer a question from the wiki context

Step 12: Show the Generated Wiki Files

These example results are perfect to show your readers.

`Index.md`

# Local Wiki Index

- [C# for AI Development](Articles/csharp-ai-development.md)

`SCHEMA.md`

# LLM Wiki Schema

## Goal
Maintain a local markdown wiki from source documents.

## Ingestion Workflow
1. Read new source document.
2. Summarize key points with technical accuracy.
3. Create or update one markdown article in `Articles/`.
4. Ensure `Index.md` contains one bullet link per article.
5. Keep filenames kebab-case and `.md`.

## Query Workflow
1. Use only article/index content provided as context.
2. Answer concisely and cite article filenames used.
3. If context is insufficient, say information is insufficient.

`csharp-ai-development.md`

# C# for AI Development

C# is a strong choice for building AI solutions, offering robust language features and a mature ecosystem.

## Key Advantages

- **Strong Typing & Tooling**: Static typing reduces runtime errors, while mature IDEs and debugging tools improve developer productivity.
- **Package Management**: NuGet provides reliable dependency management for complex projects.
- **Production-Ready Infrastructure**: The .NET ecosystem supports building scalable services, background workers, APIs, and seamless cloud integration.

## Local LLM Integration

Developers can run local large language models via **Ollama**, using open-source libraries such as:

- **OllamaSharp**: A C# client for interacting with Ollama.
- **Semantic Kernel**: Microsoft's SDK for integrating AI services into applications.

## Use Cases

This stack is particularly effective for **private knowledge workflows**, such as local markdown wikis with document ingestion and question-answering capabilities, ensuring data remains on-premise.

These examples make the demo much more concrete and easier for readers to trust.

Why This POC Is Good

This POC is simple, but it teaches many important engineering ideas:

local model integration in C#
markdown-based AI knowledge design
AI-assisted ingestion workflow
safe structured output parsing
file-based knowledge management
query-time synthesis from curated context

It is a very good educational bridge between:

plain prompt engineering
file-based knowledge systems
and full RAG architectures

Limitations of This POC

Be honest with your readers. This demo is useful, but it is still a demo.

Current limitations:

it is console-based only
article selection is simple and file-based
there is no embedding or semantic ranking layer
article context size is manually bounded
source attribution is prompt-based, not enforced by retrieval metadata
large wiki collections may require a hybrid or full RAG architecture later

That is okay. Simplicity is a feature here.

How to Extend It Later

If your readers want to continue, they can add:

command-line arguments for custom ingestion and queries
ASP.NET Core Minimal API endpoints
Blazor UI for article management
stronger JSON schema validation
better article ranking before query
Semantic Kernel orchestration
hybrid wiki + RAG support
file watchers for automatic wiki refresh

A nice next-step architecture could be:

LLM Wiki for curated stable knowledge
RAG for large and dynamic long-tail knowledge

That gives the best of both worlds.

Conclusion

We built a practical LLM Wiki POC in C# using .NET 8, Ollama, OllamaSharp, markdown files, and the kimi-k2.6:cloud model.

More importantly, we learned a design lesson that is easy to forget in modern AI work:

Not every problem needs RAG first.

Sometimes, the best answer is a clean, curated, lovingly maintained wiki.

If your knowledge is small, stable, and important, a markdown-first LLM Wiki can be wonderfully effective. It is easy to understand, easy to debug, easy to version-control, and easy to teach.

Then, when your world grows larger, you can invite RAG to the party.

Happy coding, and may your markdown always stay tidy.

Love C# & AI!

Starting to Build a One‑Person Company on Azure with OpenClaw (No Code, Just Chat)

David Au Yeung — Fri, 24 Apr 2026 19:35:25 +0000

This is a submission for the OpenClaw Writing Challenge

What I Built

After chatting with a few OpenClaw experts, I learned that most people use OpenClaw primarily for OPC.

That made me realize that this project could be used as a general platform for building AI staffs, not just for that single use case.

So I spun up OpenClaw on an Azure VM and started building.

I built a beta version of an automated daily campaign-letter summarizer on Azure using OpenClaw. Every morning at 9am, my agent scans a folder of campaign letters, summarizes them, and writes a clean daily report.

The most interesting part?

I didn't write any .claw files, YAML, or Python glue code manually.

Instead, I discovered that OpenClaw can create skills and cron tasks directly through conversation, which turned out to be the most reliable way to build automation.

I chose the cloud for the PoC because it avoids running this on my personal computer. After the trial, I can shut down and delete the Azure resources, minimizing ongoing costs and reducing exposure of my data and environment.

This project became my first step toward a "one-person AI company", a system that runs tasks for me automatically, every day.

How I Used OpenClaw

1. Setting Up the Azure VM

I deployed an Ubuntu VM on Azure to host OpenClaw. This gave me a stable, always-on environment for scheduled tasks.

2. Installing WSL + Ubuntu

Inside the VM, I used WSL to create a clean Ubuntu environment. This kept OpenClaw isolated and easy to reset.

wsl --install

3. Installing OpenClaw

I installed OpenClaw using the official script:

curl "fsSL https://get.openclaw.ai/install.sh | bash

Then launched the TUI:

openclaw tui

This dropped me into the interactive agent environment.

(This is a security reminder. You're worth taking the time to read it.)

4. Upgrading Ollama to Cloud Pro

A free Ollama API key caused authentication and provider errors. Switching to Ollama Cloud Pro solved everything instantly.
(so, I paid for a month for this PoC, which was $20 USD (˵ ͡° ͜ʖ ͡°˵))

My agent now runs on:

ollama/kimi-k2.5:cloud

Then in TUI:

/model ollama/kimi-k2.5:cloud

5. Creating the Skill (Just by Asking)

At first, I tried to follow the docs and create skills manually by writing Python files and placing them under:

~/.openclaw/workspaces/main/skills/

Those never loaded properly in my environment.

The real breakthrough came when I stopped fighting the filesystem and simply asked the agent in chat:

"Create the skill that summarizes campaign letters from a folder."

and showed him the example:

from claw import skill
import os

@skill
def summarize_campaign_letters(folder: str = "~/openclaw/campaign_letters"):
    folder = os.path.expanduser(folder)
    summaries = []

    for filename in os.listdir(folder):
        path = os.path.join(folder, filename)
        if not os.path.isfile(path):
            continue

        with open(path, "r", encoding="utf-8") as f:
            content = f.read()

        summary = skill.llm(
            f"Summarize the following campaign letter in 5 bullet points:\n\n{content}"
        )

        summaries.append(f"## {filename}\n{summary}\n")

    if not summaries:
        return "No campaign letters found."

    return "\n".join(summaries)

Then OpenClaw generated the skill, and the /skill command just worked:

/skill summarize_campaign_letters "~/openclaw/campaign_letters"

Under the hood, the Python script that actually runs lives at:

~/.npm-global/lib/node_modules/openclaw/skills/summarize-campaign-letters/scripts/summarize.py

6. Creating the Daily Automation (Cron via Chat)

My agent didn't have a /schedule command, so OpenClaw offered to create a cron job instead.

I simply chatted:

Yes, create one.
Daily summary at 9am
run /skill summarize_campaign_letters

OpenClaw generated the cron entry automatically.

Reminder: Gateway is running but in read-only mode. The cron job needs write capability to create jobs.

Now every morning at 9am (HKT), the agent runs:

/skill summarize_campaign_letters

and writes the output into my reports folder.

Demo

Here's how the system behaves:

I place text files into the ~/openclaw/campaign_letters folder.
At 9am, the cron job runs.
OpenClaw summarizes each letter.
A new campaign-summary.md appears in my reports folder.

This can easily be extended to:

Email delivery
WhatsApp notifications
PDF OCR
Multi-step workflows

But even the basic version already saves me time every morning.

What I Learned

1. Chat-Driven Creation Beats Manual Files

I tried to manually place Python skills under ~/.openclaw/workspaces/main/skills/ and reload them. But the path and startup/loading behavior made it fragile.

When I simply described what I wanted in natural language, and let OpenClaw use its own skill-creation flow, it was:

Faster
Self‑correcting (the agent asks clarifying questions and fixes its own mistakes)
Far more adaptive to rapid changes

2. Cron Is the Real Scheduler in My Setup

In my setup, the agent didn’t have a /schedule command. But it could:

Inspect existing cron jobs
Propose new ones
Write/update them for me

So instead of fighting for a missing command, I let the agent set up cron directly.

3. You Can Build Automation, But Treat AI Output as Untrusted

OpenClaw can create skills for you, and that's powerful, but it also means the system is "close to" something that can hallucinate.

If the AI generates the wrong skill code, wrong paths, or an unsafe workflow, your automation could run the wrong actions automatically (every day), which is exactly the kind of failure that's easy to miss.

So the key lesson is: use AI for building, but verify before trusting.

For example:

Review the created skills/tasks before enabling the automation
Start with a small test dataset and a short run window
Add guardrails (e.g., permissions, allowed folders, simple sanity checks on outputs)
Keep the blast radius small-especially in the first PoC run

That's how you get the speed of AI-driven setup without letting hallucinations silently turn into risk.

Just remember:

ClawCon Michigan

I didn't attend ClawCon Michigan, but I followed the event online and enjoyed seeing how others used OpenClaw creatively. This challenge pushed me to build something practical and automated, and I'm glad I did.

Love AI!

AI, Hope, and Healing: Can We Build Our Own Personalized mRNA Cancer Vaccine Pipeline?

David Au Yeung — Sat, 18 Apr 2026 08:45:49 +0000

Introduction

When people talk about Artificial Intelligence today, the conversation often revolves around chatbots, image generators, or productivity tools. But a recent story caught my attention and made me rethink what AI might mean for the future of medicine.

An Australian tech entrepreneur, Paul Conyngham, used AI tools, including ChatGPT and Google DeepMind's AlphaFold, to explore a personalized mRNA cancer vaccine for his dog Rosie, who had been diagnosed with terminal cancer. Rosie's condition improved, and the story quickly spread across global media.

This case is not a scientific breakthrough, nor is it a reproducible medical treatment. But it symbolizes something important:

AI is lowering the barrier for ordinary people to understand complex biology.

As someone who has lost both my father and sister to cancer, this story hit close to home. It made me wonder - not whether AI can cure cancer today, but whether AI can help us learn, innovate, and accelerate the path toward better treatments tomorrow.

This article explores:

✅ How tumor DNA sequencing leads to mutation discovery
✅ How DNA mutations become protein mutations
✅ Where AlphaFold fits (and where it does not)
✅ How a simplified C# demo can mirror that real biological flow
✅ Why safety, rigor, and validation always matter

Important: This project is for learning and inspiration only. It is not a medical tool and must not be used for diagnosis, treatment, or experimentation.

From Tumor DNA to Vaccine: The Real Scientific Workflow

To understand Rosie’s story, we need to understand how personalized cancer vaccines are actually developed.

Step 1 - Tumor DNA Sequencing

Cancer begins with DNA mutations.

In real oncology workflows:

A tumor biopsy is taken.
Tumor DNA is sequenced.
The patient’s normal DNA is sequenced.
Bioinformatics pipelines compare the two.
Somatic mutations unique to the tumor are identified.

These mutations are changes in the DNA letters:

A, T, C, G

Example DNA change:

Normal:  CGA
Tumor:   CAT

That may change the encoded amino acid.

Step 2 - DNA Mutation → Protein Mutation

DNA encodes proteins using triplet codons.

Each 3‑base codon → 1 amino acid.

Example:

DNA: CGA → Arginine (R)
DNA: CAT → Histidine (H)

Mutation result:

R175H

Meaning:

Original amino acid: R
Position: 175
New amino acid: H

This is called a missense mutation.

These altered proteins may generate neoantigens - small peptides the immune system has never seen before.

That is the foundation of personalized cancer vaccines.

Step 3 - From Mutated Protein to Neoantigen

The immune system does NOT see full proteins.

It sees short fragments:

Usually 8-11 amino acids
Presented by HLA molecules

So the real pipeline becomes:

Tumor DNA → Protein mutation → Mutant peptide → HLA binding prediction → Vaccine candidate

This requires:

Variant calling pipelines
Peptide extraction algorithms
HLA binding prediction models
Immunogenicity scoring
Wet‑lab validation
Clinical trials

AI assists parts of this process.

It does not replace biological validation.

Where AlphaFold Fits, and Where It Does Not

AlphaFold provides precomputed 3D structure predictions for wild‑type proteins.

These models are available through the official AlphaFold Protein Structure Database, jointly operated by Google DeepMind and EMBL‑EBI.

AlphaFold does not:

Identify mutations
Predict immune response
Predict neoantigen binding
Design vaccines
Predict mutated protein structures
Replace clinical validation

However, AlphaFold can help provide structural context:

Is the mutated residue surface‑exposed?
Is it inside a functional domain?
Is it near an active site?

This is context, not immunogenic proof.

How Our Educational C# Demo Mirrors the Real Pipeline

We simulate the workflow safely:

Real World	Demo Equivalent
Tumor sequencing	Synthetic mutation injection
Variant calling	Protein comparison
Missense mutation	Amino acid change string
Neoantigen extraction	9‑mer peptide builder
mRNA construct	Codon assembly

This preserves the shape of the real scientific pipeline without claiming medical validity.

Full Educational C# Example

DNA → Protein → Mutation Detection → Neoantigen → mRNA Construct

This demo:

Fetches a wild-type protein sequence from the AlphaFold API (with a safe fallback sequence if the API is unavailable).
Reverse-translates the protein into a synthetic coding DNA sequence.
Introduces a synthetic tumor-like point mutation in DNA.
Translates mutated DNA back into protein.
Detects amino acid changes (missense-style mutation strings, e.g., A11T).
Extracts 9-mer mutant peptide windows as neoantigen candidates.
Assembles those peptide candidates into a simplified educational mRNA sequence.

The AlphaFold API retrieves precomputed wild‑type models from the official database.

It does not run new structure predictions.

✅Program.cs

using MyPlaygroundApp.Utils;

class Program
{
    static async Task Main(string[] args)
    {
        Console.WriteLine("DNA -> Protein Mutation Detection Demo");
        Console.WriteLine("----------------------------------------");
        Console.WriteLine();

        string accession = "Q5VSL9";

        using var client = new AlphaFoldClient();
        var alphaEntry = await client.GetFirstPredictionAsync(accession);

        if (alphaEntry == null || string.IsNullOrWhiteSpace(alphaEntry.Sequence))
        {
            Console.WriteLine("AlphaFold fetch failed. Using synthetic fallback sequence.");
            alphaEntry = new AlphaFoldPrediction
            {
                Gene = accession,
                Sequence = "MKWVTFISLLFLFSSAYSRGVFRRDAHKSEVAHRFKDLGE"
            };
        }

        Console.WriteLine($"Gene: {alphaEntry.Gene}");
        Console.WriteLine($"Protein Length: {alphaEntry.Sequence.Length}");
        Console.WriteLine();

        string referenceProtein = alphaEntry.Sequence;
        string referenceDna = DnaUtils.ReverseTranslateProtein(referenceProtein);

        Console.WriteLine("Generated dummy coding DNA.");
        Console.WriteLine($"DNA length: {referenceDna.Length}");
        Console.WriteLine();

        string mutatedDna = DnaUtils.IntroducePointMutation(referenceDna, codonIndex: 10);

        Console.WriteLine("Introduced synthetic somatic mutation.");
        Console.WriteLine();

        string mutatedProtein = DnaUtils.TranslateDna(mutatedDna);
        var mutations = MutationDetector.FindMutations(referenceProtein, mutatedProtein);

        var neoantigens = mutations
            .Select((m, index) =>
            {
                var positionDigits = new string(m.Where(char.IsDigit).ToArray());
                var position = int.TryParse(positionDigits, out var parsed) ? parsed : 1;
                var mutationIndex = Math.Max(0, Math.Min(mutatedProtein.Length - 1, position - 1));
                var start = Math.Max(0, mutationIndex - 4);
                var length = Math.Min(9, mutatedProtein.Length - start);
                var peptide = mutatedProtein.Substring(start, length).PadRight(9, 'A');

                return new NeoantigenSummary
                {
                    Rank = index + 1,
                    Gene = alphaEntry.Gene,
                    SourceMutation = m,
                    MutantPeptideSequence = peptide,
                    CompositeScore = 0.9 - (index * 0.05)
                };
            })
            .ToList();

        var codons = new Dictionary<char, string>
        {
            ['A'] = "GCC",
            ['C'] = "UGC",
            ['D'] = "GAC",
            ['E'] = "GAG",
            ['F'] = "UUC",
            ['G'] = "GGC",
            ['H'] = "CAC",
            ['I'] = "AUC",
            ['K'] = "AAG",
            ['L'] = "CUG",
            ['M'] = "AUG",
            ['N'] = "AAC",
            ['P'] = "CCC",
            ['Q'] = "CAG",
            ['R'] = "CGG",
            ['S'] = "AGC",
            ['T'] = "ACC",
            ['V'] = "GUG",
            ['W'] = "UGG",
            ['Y'] = "UAC"
        };

        var mrnaBuilder = new System.Text.StringBuilder();
        foreach (var peptide in neoantigens.Select(n => n.MutantPeptideSequence))
        {
            foreach (var aa in peptide)
            {
                mrnaBuilder.Append(codons.GetValueOrDefault(aa, "NNN"));
            }
        }

        var mrnaSequence = mrnaBuilder.Length > 0 ? mrnaBuilder.ToString() : "AUG";

        Console.WriteLine("Detected Amino Acid Mutations:");
        foreach (var m in mutations)
        {
            Console.WriteLine($" - {m}");
        }

        Console.WriteLine();
        Console.WriteLine("Neoantigens:");
        foreach (var neo in neoantigens)
        {
            Console.WriteLine($" - #{neo.Rank} {neo.MutantPeptideSequence} ({neo.SourceMutation})");
        }

        Console.WriteLine();
        Console.WriteLine($"mRNA Sequence: {mrnaSequence}");

        Console.WriteLine();
        Console.WriteLine("Demo complete.");
    }
}

✅ AlphaFold Client

public sealed class AlphaFoldClient : IDisposable
{
    private readonly HttpClient _http;
    private static readonly Uri PrimaryBaseAddress = new("https://alphafold.com/api/");
    private static readonly Uri SecondaryBaseAddress = new("https://alphafold.ebi.ac.uk/api/");

    public AlphaFoldClient(HttpClient? httpClient = null)
    {
        _http = httpClient ?? new HttpClient
        {
            BaseAddress = PrimaryBaseAddress
        };

        _http.Timeout = TimeSpan.FromSeconds(30);
        _http.DefaultRequestHeaders.Accept.ParseAdd("application/json");
        _http.DefaultRequestHeaders.UserAgent.ParseAdd("Mozilla/5.0 (Windows NT 10.0; Win64; x64) MyPlaygroundApp/1.0");
    }

    public async Task<AlphaFoldPrediction?> GetFirstPredictionAsync(string accession, CancellationToken cancellationToken = default)
    {
        try
        {
            var encodedAccession = Uri.EscapeDataString(accession);
            var list = await TryGetPredictionListAsync(PrimaryBaseAddress, encodedAccession, cancellationToken)
                ?? await TryGetPredictionListAsync(SecondaryBaseAddress, encodedAccession, cancellationToken);

            if (list is null)
            {
                return null;
            }

            return list?.FirstOrDefault();
        }
        catch
        {
            return null;
        }
    }

    private async Task<List<AlphaFoldPrediction>?> TryGetPredictionListAsync(Uri baseAddress, string encodedAccession, CancellationToken cancellationToken)
    {
        try
        {
            _http.BaseAddress = baseAddress;
            using var response = await _http.GetAsync($"prediction/{encodedAccession}", cancellationToken);
            if (!response.IsSuccessStatusCode)
            {
                return null;
            }

            var json = await response.Content.ReadAsStringAsync(cancellationToken);
            return JsonSerializer.Deserialize<List<AlphaFoldPrediction>>(json,
                new JsonSerializerOptions
                {
                    PropertyNameCaseInsensitive = true
                });
        }
        catch
        {
            return null;
        }
    }

    public void Dispose()
    {
        _http.Dispose();
    }
}

public class AlphaFoldPrediction
{
    [JsonPropertyName("sequence")]
    public string Sequence { get; set; } = "";

    [JsonPropertyName("gene")]
    public string Gene { get; set; } = "";
}

✅ DNA Utility (Translation + Mutation)

public static class DnaUtils
{
    // Non-technical explanation:
    // DNA is written with four letters (A, T, C, G). Cells read DNA in groups of 3 letters called "codons".
    // Each codon maps to one protein building block (an amino acid), represented here by a single letter.
    // Example: TTT -> F (Phenylalanine).
    // This table uses the standard genetic code and includes all codons (including stop codons marked as '*').
    private static readonly Dictionary<string, char> CodonTable = new()
    {
        ["TTT"] = 'F', ["TTC"] = 'F', ["TTA"] = 'L', ["TTG"] = 'L',
        ["TCT"] = 'S', ["TCC"] = 'S', ["TCA"] = 'S', ["TCG"] = 'S',
        ["TAT"] = 'Y', ["TAC"] = 'Y', ["TAA"] = '*', ["TAG"] = '*',
        ["TGT"] = 'C', ["TGC"] = 'C', ["TGA"] = '*', ["TGG"] = 'W',

        ["CTT"] = 'L', ["CTC"] = 'L', ["CTA"] = 'L', ["CTG"] = 'L',
        ["CCT"] = 'P', ["CCC"] = 'P', ["CCA"] = 'P', ["CCG"] = 'P',
        ["CAT"] = 'H', ["CAC"] = 'H', ["CAA"] = 'Q', ["CAG"] = 'Q',
        ["CGT"] = 'R', ["CGC"] = 'R', ["CGA"] = 'R', ["CGG"] = 'R',

        ["ATT"] = 'I', ["ATC"] = 'I', ["ATA"] = 'I', ["ATG"] = 'M',
        ["ACT"] = 'T', ["ACC"] = 'T', ["ACA"] = 'T', ["ACG"] = 'T',
        ["AAT"] = 'N', ["AAC"] = 'N', ["AAA"] = 'K', ["AAG"] = 'K',
        ["AGT"] = 'S', ["AGC"] = 'S', ["AGA"] = 'R', ["AGG"] = 'R',

        ["GTT"] = 'V', ["GTC"] = 'V', ["GTA"] = 'V', ["GTG"] = 'V',
        ["GCT"] = 'A', ["GCC"] = 'A', ["GCA"] = 'A', ["GCG"] = 'A',
        ["GAT"] = 'D', ["GAC"] = 'D', ["GAA"] = 'E', ["GAG"] = 'E',
        ["GGT"] = 'G', ["GGC"] = 'G', ["GGA"] = 'G', ["GGG"] = 'G'
    };

    private static readonly Dictionary<char, string> ReverseTable =
        CodonTable.GroupBy(x => x.Value)
                  .ToDictionary(g => g.Key, g => g.First().Key);

    // Reads DNA in 3-base codons and converts each recognized codon into one amino acid.
    public static string TranslateDna(string dna)
    {
        var protein = new List<char>();
        for (int i = 0; i + 2 < dna.Length; i += 3)
        {
            var codon = dna.Substring(i, 3);
            if (CodonTable.TryGetValue(codon, out char aa))
                protein.Add(aa);
        }
        return new string(protein.ToArray());
    }

    // Converts an amino-acid sequence into a synthetic coding DNA string using one representative codon per amino acid.
    public static string ReverseTranslateProtein(string protein)
    {
        return string.Concat(protein.Select(aa =>
            ReverseTable.ContainsKey(aa) ? ReverseTable[aa] : "GCT"));
    }

    // Simulates a single point mutation and prefers a non-synonymous change (amino acid actually changes).
    public static string IntroducePointMutation(string dna, int codonIndex)
    {
        var pos = codonIndex * 3;
        if (pos + 2 >= dna.Length)
        {
            return dna;
        }

        var originalCodon = dna.Substring(pos, 3);
        if (!CodonTable.TryGetValue(originalCodon, out var originalAminoAcid))
        {
            return dna;
        }

        var arr = dna.ToCharArray();
        var bases = new[] { 'A', 'T', 'C', 'G' };

        for (var offset = 0; offset < 3; offset++)
        {
            var index = pos + offset;
            var originalBase = arr[index];

            foreach (var candidateBase in bases)
            {
                if (candidateBase == originalBase)
                {
                    continue;
                }

                arr[index] = candidateBase;
                var mutatedCodon = new string(arr, pos, 3);

                if (!CodonTable.TryGetValue(mutatedCodon, out var mutatedAminoAcid))
                {
                    continue;
                }

                if (mutatedAminoAcid != originalAminoAcid && mutatedAminoAcid != '*')
                {
                    return new string(arr);
                }
            }

            arr[index] = originalBase;
        }

        return dna;
    }
}

✅ Mutation Detector

public static class MutationDetector
{
    public static List<string> FindMutations(string reference, string mutated)
    {
        var mutations = new List<string>();
        int len = Math.Min(reference.Length, mutated.Length);

        for (int i = 0; i < len; i++)
        {
            if (reference[i] != mutated[i])
            {
                mutations.Add($"{reference[i]}{i + 1}{mutated[i]}");
            }
        }

        return mutations;
    }
}

Example Output

This mirrors:

Tumor DNA mutation → missense change → neoantigen candidate → mRNA construct

Safely and conceptually.

Why This Matters

Without explaining the mutation pipeline clearly, people might think:

"AI designs cancer vaccines."

It does not.

The real power lies in combining:

Sequencing
Variant calling
Structural biology
Immunology
AI-assisted analysis
Clinical validation

AI amplifies understanding.

It does not replace medicine.

Conclusion

AI is transforming how we think about biology, not by giving us instant cures, but by giving us tools to understand, explore, and innovate. Stories like Rosie’s remind us that hope often begins with curiosity, and that technology can empower people in ways we never imagined.

But technology alone is not enough. For AI‑enabled healthcare to truly benefit patients, we need thoughtful collaboration between researchers, clinicians, policymakers, and regulatory bodies. That means updating outdated frameworks, supporting responsible innovation, and building pathways that allow safe, evidence‑based personalized medicine to reach the people who need it.

Let's use AI not just to make life easier, but to make life better.

Reference:

unwire.hk: 愛狗患癌工程師搵 AI 幫手 ChatGPT 設計癌症疫苗腫瘤縮 75% 重拾活力
Yahoo Finance: Man's dog was riddled with tumors and dying. He used ChatGPT to design a custom cancer vaccine, stunning researchers
AlphaFold: Programmatic access API endpoints

Love C# & AI & Life!

My 2026 Milestone #1: Achieved Alibaba Cloud Product Capability Certification (AI Stack Delivery Engineer)!

David Au Yeung — Mon, 30 Mar 2026 17:33:42 +0000

On March 5, 2026, I achieved the

Product Capability Certification: Apsara Stack AI Stack Delivery

under Alibaba Cloud.

This certification is currently more recognized within China and the Alibaba Cloud partner ecosystem, so I'd like to share some context for my global followers about what it represents - and why it matters in today's AI infrastructure landscape.

Why Does Alibaba Cloud Offer an On‑Prem AI Solution?

When most people think of Alibaba Cloud, they think of public cloud services - ECS, OSS, databases, and cloud-native platforms.

However, enterprise AI adoption has introduced new requirements:

Large Language Model (LLM) deployment
GPU-intensive workloads
Data sovereignty and regulatory compliance
Low-latency internal AI systems
Fully private AI environments

Many industries - especially finance, government, telecom, and large manufacturing - cannot move sensitive data to public cloud AI services.

To address this, Alibaba Cloud provides AI Stack as part of Apsara Stack, its enterprise-grade on-prem cloud platform.

Think of it as:

Cloud-native AI capability deployed inside your own data center.

What Is AI Stack?

AI Stack is a full-stack private AI infrastructure platform built on Apsara Stack, designed for enterprise environments.

It spans multiple layers of the stack:

1️⃣ Infrastructure Layer (IaaS)

High-performance GPU servers (PCIe / high-density architecture)
Multi-node GPU cluster orchestration
High-speed networking
Storage systems

2️⃣ Platform Layer (PaaS)

Database services (e.g., PolarDB, MySQL)
Middleware and application runtime services
Logging and monitoring services
API gateway and service management
Identity and access control (RBAC)

These PaaS components support:

Model metadata storage
Logging and audit trails
Configuration management
Service orchestration
Enterprise governance

3️⃣ AI Service Layer

Model inference engines
Internal AI service exposure (API-based)
SaaS-style enterprise AI services
MaaS (Model as a Service) enablement

It is not just hardware.

It is not just AI software.

It is an integrated enterprise AI cloud stack running inside a private data center.

Why This Matters in 2026

Today, most AI discussions focus on:

Model size (70B, 200B+)
Benchmarks
Prompt engineering

But what often gets overlooked is the infrastructure layer.

Running large models in production requires:

High-density GPU architecture
High-speed interconnect design
Power and cooling planning
Performance validation
Operational monitoring
SLA-backed maintenance processes

AI innovation is not only about building models -

it's about delivering them reliably at enterprise scale.

This certification focuses on that operational and delivery foundation.

About the Certification

The official certification is:

Product Capability Certification: Apsara Stack AI Stack Delivery

Category: Product Capability Certification

Exam Duration: 90 minutes

Format: 50 questions (single-choice and multiple-choice)

Testing Option: Online, non-proctored

Language: Chinese

Course Duration: 160 minutes (on-demand)

⚠️ Important clarification:

This certification is currently available only to Alibaba Cloud Partners.

It is designed for engineers and service providers responsible for delivering AI-driven solutions on Apsara Stack for enterprise customers.

Course Coverage

The official preparation course covers:

AI Stack Product Overview
AI Stack Architecture and Console Introduction
AI Stack Delivery and Deployment Overview
AI Stack Hardware Maintenance Process

The focus is strongly on delivery execution and operational readiness - not just theoretical architecture diagrams.

What You Should Know Before Taking This Exam

This is not an entry-level certification. It assumes real infrastructure experience.

1️⃣ Cloud & Infrastructure Fundamentals

Compute, storage, networking basics
Virtualization and containerization
IAM and RBAC concepts

2️⃣ GPU & AI Infrastructure Basics

PCIe vs high-density GPU architecture
Importance of inter-GPU bandwidth
Inference vs training fundamentals
Performance factors (precision, concurrency, throughput)

3️⃣ Enterprise AI Delivery Mindset

AI Stack delivery requires understanding:

Site survey and power planning
GPU density and rack design
High-speed networking requirements
Deployment workflows (single-node vs multi-node clusters)
Acceptance testing processes
SLA models (NBD, 7×24×4, etc.)
Structured troubleshooting methodology

It also helps to understand how infrastructure enables:

Private AI platforms
Internal SaaS-style AI services
Enterprise MaaS (Model as a Service)
Hybrid AI architectures

What This Exam Really Tests

This exam emphasizes real-world delivery scenarios, not memorization.

It tests whether you understand:

Architecture trade-offs (cost vs performance vs scalability)
Deployment processes
Failure handling under operational pressure
Enterprise-grade AI operations
Hardware maintenance procedures

In simple terms:

It's not just about running a model.

It's about delivering AI infrastructure as a reliable enterprise system.

Why This Is Relevant Beyond Alibaba Cloud

Even if you are not in the Alibaba Cloud ecosystem, the global trend is clear:

Enterprises increasingly demand private AI capabilities
GPU clusters are becoming core infrastructure
AI infrastructure engineering is emerging as a specialized discipline

Understanding how AI platforms are delivered on-prem broadens your architectural perspective - even if you primarily work with AWS, Azure, or GCP.

Cloud is no longer just public cloud.

Hybrid and private AI infrastructure are becoming strategic enterprise investments.

Where to Learn More

This certification is offered through Alibaba Cloud Academy:

https://www.alibabacloud.com/en/academy/product-capability-certification-ai-stack-delivery

Alibaba Cloud Academy is the official training and certification division of Alibaba Cloud, offering professional certifications, capability certifications, e-learning courses, and hands-on labs.

However, please note again:

This specific certification is currently restricted to Alibaba Cloud Partners.

Reflection

Previously, I achieved the Microsoft Azure Solutions Architect Expert certification, which focuses heavily on cloud architecture design.

This milestone complements that experience by focusing on:

AI infrastructure delivery
Enterprise on-prem cloud platforms
GPU cluster deployment
Operational execution

One validates architecture thinking.

The other validates delivery execution.

Both perspectives are essential in today's AI-driven enterprise environment.

What's Next?

With certifications in both:

Microsoft Azure (cloud architecture)
Alibaba Cloud AI Stack Delivery (enterprise AI infrastructure)

I will continue deepening my focus on:

Enterprise AI architecture
Hybrid AI platform design
Large-scale GPU infrastructure optimization

Excited for what 2026 will bring.

Here's to building not just cloud solutions -

but real AI infrastructure for enterprises.

Love AI!

PostgreSQL SQL Recap: Building Strong Foundational SQL Skills

David Au Yeung — Sat, 07 Feb 2026 07:29:28 +0000

1. Introduction

PostgreSQL (Postgres) is a powerful, open‑source relational database known for its reliability and strong SQL compliance. If you understand how to:

Design tables
Insert and query data
Join tables together
Aggregate and filter results

you already have the tools needed for most production systems.

We'll learn these concepts using:

Customers
Products
Orders
Order items
Promotions

2. Exercise Setup - Core Tables

Customers Table

Stores customer information.

CREATE TABLE Customers (
    CustomerID      BIGSERIAL PRIMARY KEY,
    LastName        VARCHAR(100) NOT NULL,
    FirstName       VARCHAR(100) NOT NULL,
    DOB             DATE NOT NULL,
    IsDeleted       BOOLEAN NOT NULL DEFAULT FALSE,
    CreateBy        VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    CreateDate      TIMESTAMP NOT NULL DEFAULT NOW(),
    ModifyBy        VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    ModifyDate      TIMESTAMP NOT NULL DEFAULT NOW(),
    CHECK (EXTRACT(YEAR FROM DOB) >= 1900)
);

Products Table

Stores products available for purchase.

CREATE TABLE Products (
    ProductID         BIGSERIAL PRIMARY KEY,
    ProductName       VARCHAR(1000) NOT NULL,
    ProductCode       VARCHAR(1000) NOT NULL,
    AvailableQuantity INT NOT NULL,
    IsDeleted         BOOLEAN NOT NULL DEFAULT FALSE,
    CreateBy          VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    CreateDate        TIMESTAMP NOT NULL DEFAULT NOW(),
    ModifyBy          VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    ModifyDate        TIMESTAMP NOT NULL DEFAULT NOW(),
    CHECK (AvailableQuantity >= 0)
);

Orders Table

Represents a purchase made by a customer.

CREATE TABLE Orders (
    OrderID       BIGSERIAL PRIMARY KEY,
    CustomerID    BIGINT,
    OrderNumber   VARCHAR(1000) NOT NULL,
    OrderDate     TIMESTAMP NOT NULL,
    IsDeleted     BOOLEAN NOT NULL DEFAULT FALSE,
    CreateBy      VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    CreateDate    TIMESTAMP NOT NULL DEFAULT NOW(),
    ModifyBy      VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    ModifyDate    TIMESTAMP NOT NULL DEFAULT NOW(),
    FOREIGN KEY (CustomerID) REFERENCES Customers(CustomerID)
);

OrderItems Table

Breaks orders into product line items.

CREATE TABLE OrderItems (
    OrderItemID BIGSERIAL PRIMARY KEY,
    OrderID     BIGINT,
    ProductID   BIGINT,
    Quantity    INT NOT NULL,
    IsDeleted   BOOLEAN NOT NULL DEFAULT FALSE,
    CreateBy    VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    CreateDate  TIMESTAMP NOT NULL DEFAULT NOW(),
    ModifyBy    VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    ModifyDate  TIMESTAMP NOT NULL DEFAULT NOW(),
    FOREIGN KEY (OrderID) REFERENCES Orders(OrderID),
    FOREIGN KEY (ProductID) REFERENCES Products(ProductID),
    CHECK (Quantity > 0)
);

3. Promotions Setup

Promotions Table

CREATE TABLE Promotions (
    PromotionID   BIGSERIAL PRIMARY KEY,
    PromotionName VARCHAR(1000),
    PromotionCode VARCHAR(1000),
    ActiveFrom    TIMESTAMP NOT NULL DEFAULT '1900-01-01',
    ActiveTo      TIMESTAMP NOT NULL DEFAULT '2999-12-31',
    IsActive      BOOLEAN NOT NULL DEFAULT TRUE,
    IsDeleted     BOOLEAN NOT NULL DEFAULT FALSE,
    CreateBy      VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    CreateDate    TIMESTAMP NOT NULL DEFAULT NOW(),
    ModifyBy      VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    ModifyDate    TIMESTAMP NOT NULL DEFAULT NOW()
);

OrderPromotions Table

(One order can apply multiple promotions)

CREATE TABLE OrderPromotions (
    OrderPromotionID BIGSERIAL PRIMARY KEY,
    OrderID          BIGINT,
    PromotionID      BIGINT,
    IsDeleted        BOOLEAN NOT NULL DEFAULT FALSE,
    CreateBy         VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    CreateDate       TIMESTAMP NOT NULL DEFAULT NOW(),
    ModifyBy         VARCHAR(100) NOT NULL DEFAULT 'SYSTEM',
    ModifyDate       TIMESTAMP NOT NULL DEFAULT NOW(),
    FOREIGN KEY (OrderID) REFERENCES Orders(OrderID),
    FOREIGN KEY (PromotionID) REFERENCES Promotions(PromotionID)
);

4. Insert Sample Data

Customers

INSERT INTO Customers (LastName, FirstName, DOB) VALUES
('Au Yeung', 'David', '1980-12-31'),
('Chan', 'Peter', '1982-01-15');

Products

INSERT INTO Products (ProductName, ProductCode, AvailableQuantity) VALUES
('Android Phone', 'A0001', 100),
('iPhone', 'I0001', 100),
('iPad', 'I0002', 100);

Orders and Order Items

INSERT INTO Orders (CustomerID, OrderNumber, OrderDate)
VALUES (1, 'ORD0001', NOW());

INSERT INTO OrderItems (OrderID, ProductID, Quantity)
VALUES (1, 2, 10);

INSERT INTO Orders (CustomerID, OrderNumber, OrderDate)
VALUES (2, 'ORD0002', NOW());

INSERT INTO OrderItems (OrderID, ProductID, Quantity)
VALUES (2, 1, 5);

Promotions

INSERT INTO Promotions (PromotionName, PromotionCode, ActiveFrom, ActiveTo) VALUES
('New Year Discount', 'NY2025', '2026-01-01', '2026-01-31'),
('VIP Customer Promo', 'VIP10', '2026-01-01', '2999-12-31');

Order Promotions

INSERT INTO OrderPromotions (OrderID, PromotionID) VALUES
(1, 1),
(1, 2);

INSERT INTO OrderPromotions (OrderID, PromotionID) VALUES
(2, 1);

Inspect the Data

SELECT * FROM Customers;
SELECT * FROM Products;
SELECT * FROM Orders;
SELECT * FROM OrderItems;
SELECT * FROM Promotions;
SELECT * FROM OrderPromotions;

5. Ten Foundational SQL Questions

Which promotions are currently active?
Which promotions have never been used?
How many promotions are applied to each order?
Which orders have more than one promotion?
List all customers and their orders (including customers with none).
What is the total quantity ordered per product?
Which products have never been ordered?
What is the latest order for each customer?
Which orders were created in the last 30 days?
Which promotion is used the most?

6. Answers

1. Active Promotions

SELECT *
FROM Promotions
WHERE IsActive = TRUE
  AND IsDeleted = FALSE
  AND NOW() BETWEEN ActiveFrom AND ActiveTo;

2. Promotions Never Used

SELECT p.*
FROM Promotions p
LEFT JOIN OrderPromotions op
    ON p.PromotionID = op.PromotionID
    AND op.IsDeleted = FALSE
WHERE op.OrderPromotionID IS NULL;

3. Promotion Count per Order

SELECT OrderID, COUNT(*) AS PromotionCount
FROM OrderPromotions
WHERE IsDeleted = FALSE
GROUP BY OrderID;

4. Orders with Multiple Promotions

SELECT OrderID
FROM OrderPromotions
WHERE IsDeleted = FALSE
GROUP BY OrderID
HAVING COUNT(*) > 1;

5. Customers and Their Orders

SELECT c.CustomerID, c.FirstName, c.LastName, o.OrderID, o.OrderDate
FROM Customers c
LEFT JOIN Orders o
    ON c.CustomerID = o.CustomerID
    AND o.IsDeleted = FALSE;

6. Total Quantity per Product

SELECT p.ProductName, SUM(oi.Quantity) AS TotalOrdered
FROM Products p
JOIN OrderItems oi ON p.ProductID = oi.ProductID
WHERE oi.IsDeleted = FALSE
GROUP BY p.ProductName;

7. Products Never Ordered

SELECT p.*
FROM Products p
LEFT JOIN OrderItems oi
    ON p.ProductID = oi.ProductID
    AND oi.IsDeleted = FALSE
WHERE oi.OrderItemID IS NULL;

8. Latest Order per Customer

WITH cte AS (
    SELECT *,
           ROW_NUMBER() OVER (
               PARTITION BY CustomerID
               ORDER BY OrderDate DESC
           ) AS rn
    FROM Orders
    WHERE IsDeleted = FALSE
)
SELECT *
FROM cte
WHERE rn = 1;

9. Orders in the Last 30 Days

SELECT *
FROM Orders
WHERE OrderDate >= NOW() - INTERVAL '30 days'
  AND IsDeleted = FALSE;

10. Most Used Promotion

SELECT p.PromotionName, COUNT(*) AS UsageCount
FROM Promotions p
JOIN OrderPromotions op
    ON p.PromotionID = op.PromotionID
WHERE op.IsDeleted = FALSE
GROUP BY p.PromotionName
ORDER BY UsageCount DESC
LIMIT 1;

7. Conclusion

This PostgreSQL recap covered the most important SQL foundations:

Table design with primary and foreign keys
One‑to‑many and many‑to‑many relationships
JOIN, GROUP BY, and HAVING
Window functions for real business problems
Writing SQL that reflects real‑world questions

If you can comfortably understand and write these queries, you already have strong SQL fundamentals, regardless of database size or system complexity.

Feel free to extend this schema, add more data, or challenge yourself with new questions.

That's how real SQL mastery is built.

Step-by-Step Guide: Build a CRUD Blazor App with Entity Framework and PostgreSQL

David Au Yeung — Tue, 20 Jan 2026 03:05:17 +0000

Introduction

Happy New Year 2026 to all! This year, I want to share more basic must-learn knowledge on .NET. This tutorial is my first sharing on dev.to this year. Happy to see you all again.

Entity Framework (EF) is Microsoft's object-relational mapper (ORM) for .NET. It simplifies data access by allowing you to work with databases using .NET objects, eliminating the need for most data-access code. In this tutorial, we'll build a simple CRUD (Create, Read, Update, Delete) Blazor Server app using EF Core with PostgreSQL. We'll cover setting up the project, defining models, seeding data, and creating a basic UI for managing customers.

By the end, you'll have a functional app demonstrating EF's power for database operations.

Prerequisites

Before we begin, ensure you have the following:

Visual Studio or any C# IDE (e.g., VS Code).
.NET 10 SDK installed (download from Microsoft's site).
PostgreSQL installed and running (download from EnterpriseDB). Set up a database (e.g., "BlazorDemo") and note the connection details.

Step 1: Setting Up the Blazor Project

Create a new Blazor Server app:

dotnet new blazorserver --force

This scaffolds a basic Blazor Server project.

Step 2: Adding Entity Framework Packages

Add the necessary NuGet packages for EF Core and PostgreSQL:

dotnet add package Microsoft.EntityFrameworkCore
dotnet add package Microsoft.EntityFrameworkCore.Tools
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL

Microsoft.EntityFrameworkCore: Core EF functionality.
Microsoft.EntityFrameworkCore.Tools: For migrations and database commands.
Npgsql.EntityFrameworkCore.PostgreSQL: PostgreSQL provider.

Step 3: Creating Models

Define your data models. Create a Models folder and add classes like Customer.cs:

using System.ComponentModel.DataAnnotations;

namespace BlazorWithEntityFramework.Models
{
    public class Customer
    {
        [Key]
        public long CustomerId { get; set; }

        [Required]
        [StringLength(1000)]
        public string CustomerNumber { get; set; } = string.Empty;

        [Required]
        [StringLength(100)]
        public string LastName { get; set; } = string.Empty;

        [Required]
        [StringLength(100)]
        public string FirstName { get; set; } = string.Empty;

        [Required]
        public DateTime Dob { get; set; }

        public bool IsDeleted { get; set; } = false;

        [StringLength(100)]
        public string CreateBy { get; set; } = "SYSTEM";

        public DateTime CreateDate { get; set; } = DateTime.UtcNow;

        [StringLength(100)]
        public string ModifyBy { get; set; } = "SYSTEM";

        public DateTime ModifyDate { get; set; } = DateTime.UtcNow;
    }
}

Product.cs:

using System.ComponentModel.DataAnnotations;

namespace BlazorWithEntityFramework.Models
{
    public class Product
    {
        [Key]
        public long ProductId { get; set; }

        [Required]
        [StringLength(1000)]
        public string ProductName { get; set; } = string.Empty;

        [Required]
        [StringLength(1000)]
        public string ProductCode { get; set; } = string.Empty;

        [Required]
        [Range(0, int.MaxValue)]
        public int AvailableQuantity { get; set; }

        public bool IsDeleted { get; set; } = false;

        [StringLength(100)]
        public string CreateBy { get; set; } = "SYSTEM";

        public DateTime CreateDate { get; set; } = DateTime.UtcNow;

        [StringLength(100)]
        public string ModifyBy { get; set; } = "SYSTEM";

        public DateTime ModifyDate { get; set; } = DateTime.UtcNow;

        public ICollection<OrderItem> OrderItems { get; set; } = new List<OrderItem>();
    }
}

Order.cs:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace BlazorWithEntityFramework.Models
{
    public class Order
    {
        [Key]
        public long OrderId { get; set; }

        public long? CustomerId { get; set; }

        [Required]
        [StringLength(1000)]
        public string OrderNumber { get; set; } = string.Empty;

        [Required]
        public DateTime OrderDate { get; set; }

        public bool IsDeleted { get; set; } = false;

        [StringLength(100)]
        public string CreateBy { get; set; } = "SYSTEM";

        public DateTime CreateDate { get; set; } = DateTime.UtcNow;

        [StringLength(100)]
        public string ModifyBy { get; set; } = "SYSTEM";

        public DateTime ModifyDate { get; set; } = DateTime.UtcNow;

        [ForeignKey("CustomerId")]
        public Customer? Customer { get; set; }

        public ICollection<OrderItem> OrderItems { get; set; } = new List<OrderItem>();
    }
}

OrderItem.cs:

using System.ComponentModel.DataAnnotations;
using System.ComponentModel.DataAnnotations.Schema;

namespace BlazorWithEntityFramework.Models
{
    public class OrderItem
    {
        [Key]
        public long OrderItemId { get; set; }

        public long? OrderId { get; set; }

        public long? ProductId { get; set; }

        [Required]
        [Range(1, int.MaxValue)]
        public int Quantity { get; set; }

        public bool IsDeleted { get; set; } = false;

        [StringLength(100)]
        public string CreateBy { get; set; } = "SYSTEM";

        public DateTime CreateDate { get; set; } = DateTime.UtcNow;

        [StringLength(100)]
        public string ModifyBy { get; set; } = "SYSTEM";

        public DateTime ModifyDate { get; set; } = DateTime.UtcNow;

        [ForeignKey("OrderId")]
        public Order? Order { get; set; }

        [ForeignKey("ProductId")]
        public Product? Product { get; set; }
    }
}

Step 4: Setting Up the DbContext

Create a Data folder and add AppDbContext.cs:

using Microsoft.EntityFrameworkCore;
using BlazorWithEntityFramework.Models;

namespace BlazorWithEntityFramework.Data
{
    public class AppDbContext : DbContext
    {
        public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }

        public DbSet<Customer> Customers { get; set; }
        public DbSet<Product> Products { get; set; }
        public DbSet<Order> Orders { get; set; }
        public DbSet<OrderItem> OrderItems { get; set; }

        protected override void OnModelCreating(ModelBuilder modelBuilder)
        {
            base.OnModelCreating(modelBuilder);

            // Seed data
            modelBuilder.Entity<Customer>().HasData(
                new Customer
                {
                    CustomerId = 1,
                    CustomerNumber = "CUST0001",
                    LastName = "Au Yeung",
                    FirstName = "David",
                    Dob = new DateTime(1980, 12, 31, 0, 0, 0, DateTimeKind.Utc),
                    IsDeleted = false,
                    CreateBy = "SYSTEM",
                    CreateDate = DateTime.UtcNow,
                    ModifyBy = "SYSTEM",
                    ModifyDate = DateTime.UtcNow
                },
                new Customer
                {
                    CustomerId = 2,
                    CustomerNumber = "CUST0002",
                    LastName = "Chan",
                    FirstName = "Peter",
                    Dob = new DateTime(1982, 1, 15, 0, 0, 0, DateTimeKind.Utc),
                    IsDeleted = false,
                    CreateBy = "SYSTEM",
                    CreateDate = DateTime.UtcNow,
                    ModifyBy = "SYSTEM",
                    ModifyDate = DateTime.UtcNow
                }
            );

            modelBuilder.Entity<Product>().HasData(
                new Product
                {
                    ProductId = 1,
                    ProductName = "Android Phone",
                    ProductCode = "A0001",
                    AvailableQuantity = 100,
                    IsDeleted = false,
                    CreateBy = "SYSTEM",
                    CreateDate = DateTime.UtcNow,
                    ModifyBy = "SYSTEM",
                    ModifyDate = DateTime.UtcNow
                },
                new Product
                {
                    ProductId = 2,
                    ProductName = "iPhone",
                    ProductCode = "I0001",
                    AvailableQuantity = 100,
                    IsDeleted = false,
                    CreateBy = "SYSTEM",
                    CreateDate = DateTime.UtcNow,
                    ModifyBy = "SYSTEM",
                    ModifyDate = DateTime.UtcNow
                }
            );

            modelBuilder.Entity<Order>().HasData(
                new Order
                {
                    OrderId = 1,
                    CustomerId = 1,
                    OrderNumber = "ORD0001",
                    OrderDate = DateTime.UtcNow,
                    IsDeleted = false,
                    CreateBy = "SYSTEM",
                    CreateDate = DateTime.UtcNow,
                    ModifyBy = "SYSTEM",
                    ModifyDate = DateTime.UtcNow
                }
            );

            modelBuilder.Entity<OrderItem>().HasData(
                new OrderItem
                {
                    OrderItemId = 1,
                    OrderId = 1,
                    ProductId = 2,
                    Quantity = 10,
                    IsDeleted = false,
                    CreateBy = "SYSTEM",
                    CreateDate = DateTime.UtcNow,
                    ModifyBy = "SYSTEM",
                    ModifyDate = DateTime.UtcNow
                }
            );
        }
    }
}

Step 5: Configuring the Connection String

In appsettings.json, add:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=BlazorDemo;Username=yourusername;Password=yourpassword"
  }
}

Update Program.cs to register the DbContext:

builder.Services.AddDbContext<AppDbContext>(options => options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

And ensure DB creation:

using (var scope = app.Services.CreateScope())
{
    var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
    db.Database.EnsureCreated();
}

Step 6: Creating Migrations and Updating the Database

Generate and apply migrations:

dotnet ef migrations add InitialCreate
dotnet ef database update

EnsureCreated() in Program.cs ensures the database is created and seeded on startup. This works alongside migrations for a demo. Note that in production, you might prefer migrations exclusively for better control.

Step 7: Building the CRUD UI

Create a page like Pages/Customers.razor for managing customers:

@page "/customers"
@inject AppDbContext DbContext

<h3>Customers</h3>

@if (customers == null)
{
    <p>Loading...</p>
}
else
{
    <table class="table">
        <thead>
            <tr>
                <th>ID</th>
                <th>Customer Number</th>
                <th>Last Name</th>
                <th>First Name</th>
                <th>DOB</th>
                <th>Actions</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var customer in customers.Where(c => !c.IsDeleted))
            {
                <tr>
                    <td>@customer.CustomerId</td>
                    <td>@customer.CustomerNumber</td>
                    <td>@customer.LastName</td>
                    <td>@customer.FirstName</td>
                    <td>@customer.Dob.ToShortDateString()</td>
                    <td>
                        <button class="btn btn-primary" @onclick="() => EditCustomer(customer)">Edit</button>
                        <button class="btn btn-danger" @onclick="() => DeleteCustomer(customer)">Delete</button>
                    </td>
                </tr>
            }
        </tbody>
    </table>

    <button class="btn btn-success" @onclick="AddCustomer">Add New Customer</button>

    @if (isEditing)
    {
        <div class="modal" style="display:block;">
            <div class="modal-content">
                <h4>@(editingCustomer.CustomerId == 0 ? "Add" : "Edit") Customer</h4>
                <form>
                    <div class="form-group">
                        <label>Customer Number</label>
                        <input type="text" class="form-control" @bind="editingCustomer.CustomerNumber" />
                    </div>
                    <div class="form-group">
                        <label>Last Name</label>
                        <input type="text" class="form-control" @bind="editingCustomer.LastName" />
                    </div>
                    <div class="form-group">
                        <label>First Name</label>
                        <input type="text" class="form-control" @bind="editingCustomer.FirstName" />
                    </div>
                    <div class="form-group">
                        <label>DOB</label>
                        <input type="date" class="form-control" @bind="editingCustomer.Dob" />
                    </div>
                    <button type="button" class="btn btn-primary" @onclick="SaveCustomer">Save</button>
                    <button type="button" class="btn btn-secondary" @onclick="CancelEdit">Cancel</button>
                </form>
            </div>
        </div>
    }
}

@code {
    private List<Customer> customers = new();
    private Customer editingCustomer = new();
    private bool isEditing = false;

    protected override async Task OnInitializedAsync()
    {
        await LoadCustomers();
    }

    private async Task LoadCustomers()
    {
        customers = await DbContext.Customers.AsNoTracking().ToListAsync();
    }

    private void AddCustomer()
    {
        editingCustomer = new Customer { Dob = DateTime.UtcNow };
        isEditing = true;
    }

    private void EditCustomer(Customer customer)
    {
        editingCustomer = new Customer
        {
            CustomerId = customer.CustomerId,
            CustomerNumber = customer.CustomerNumber,
            LastName = customer.LastName,
            FirstName = customer.FirstName,
            Dob = customer.Dob,
            IsDeleted = customer.IsDeleted,
            CreateBy = customer.CreateBy,
            CreateDate = customer.CreateDate,
            ModifyBy = "USER",
            ModifyDate = DateTime.UtcNow
        };
        isEditing = true;
    }

    private async Task SaveCustomer()
    {
        if (editingCustomer.CustomerId == 0)
        {
            DbContext.Customers.Add(editingCustomer);
        }
        else
        {
            var existing = await DbContext.Customers.FindAsync(editingCustomer.CustomerId);
            if (existing != null)
            {
                DbContext.Entry(existing).CurrentValues.SetValues(editingCustomer);
            }
        }
        await DbContext.SaveChangesAsync();
        isEditing = false;
        await LoadCustomers();
    }

    private void CancelEdit()
    {
        isEditing = false;
    }

    private async Task DeleteCustomer(Customer customer)
    {
        var existing = await DbContext.Customers.FindAsync(customer.CustomerId);
        if (existing != null)
        {
            existing.IsDeleted = true;
            existing.ModifyBy = "USER";
            existing.ModifyDate = DateTime.UtcNow;
            DbContext.Customers.Update(existing);
        }
        await DbContext.SaveChangesAsync();
        await LoadCustomers();
    }
}

Add navigation in NavMenu.razor.

Step 8: Running the App

Run the app:

dotnet run

Navigate to /customers to test CRUD operations.

Conclusion

You've built a CRUD Blazor app with EF and PostgreSQL! EF simplifies database interactions, and Blazor provides a seamless UI. Experiment with more entities or features like validation.

Feel free to ask questions or expand on this. Happy coding!

Love C#!

Run SQLite in the Browser with Blazor WebAssembly (WASM) : A Practical Step‑by‑Step Guide

David Au Yeung — Sat, 27 Dec 2025 04:28:11 +0000

Introduction

In this exercise, we'll learn how to run a real SQLite database entirely in the browser using Blazor WebAssembly and sql.js.

No server.

No connection string.

No Docker.

Everything runs inside the user's browser tab, powered by WebAssembly.

We'll build a simple Blazor page that loads the popular Chinook sample database, runs SQL queries client-side, and renders the results in a table.

This approach works great for:

Offline‑first demos and prototypes
Data exploration tools
Training content and workshops
Scenarios where you want "database feel" without any backend

Step 1: Add sql.js to Your Blazor WebAssembly App

First, we need the sql.js library (SQLite compiled to WebAssembly for browsers).

Create a folder under wwwroot:

wwwroot/sqljs/

Download the following files from the official sql.js GitHub releases (or a CDN) and place them in wwwroot/sqljs/:

Your structure should look like:

wwwroot/
  sqljs/
    sql-wasm.js
    sql-wasm.wasm

Step 2: Create a Thin JavaScript Wrapper

Next, we create a small JavaScript interop layer that:

Loads sql-wasm.js and initializes SQL.js
Opens databases from byte arrays
Executes SQL and returns rows as JavaScript objects
Exports and closes databases

Add a new file: wwwroot/sqljs/sqljsInterop.js:

window.sqliteJs = {
  init: async () => {
    try {
      console.log("sqliteJs.init: Starting initialization...");
      if (window.SQL) {
        console.log("sqliteJs.init: Already initialized");
        return true;
      }

      console.log("sqliteJs.init: Loading sql-wasm.js...");
      await new Promise((resolve, reject) => {
        const s = document.createElement("script");
        s.src = "/sqljs/sql-wasm.js";
        s.onload = () => {
          console.log("sqliteJs.init: sql-wasm.js loaded successfully");
          resolve();
        };
        s.onerror = (e) => {
          console.error("sqliteJs.init: Failed to load sql-wasm.js", e);
          reject(e);
        };
        document.head.appendChild(s);
      });

      console.log("sqliteJs.init: Initializing SQL.js...");
      window.SQL = await initSqlJs({
        locateFile: f => {
          console.log("sqliteJs.init: Locating file:", f);
          return "/sqljs/" + f;
        }
      });

      window._dbs = {};
      console.log("sqliteJs.init: Initialization complete");
      return true;
    } catch (error) {
      console.error("sqliteJs.init: Error during initialization", error);
      throw error;
    }
  },

  openDb: (bytes) => {
    try {
      console.log("sqliteJs.openDb: Opening database, bytes:", bytes ? bytes.length : 0);
      const db = bytes ? new SQL.Database(new Uint8Array(bytes))
                       : new SQL.Database();
      const id = crypto.randomUUID();
      window._dbs[id] = db;
      console.log("sqliteJs.openDb: Database opened with ID:", id);
      return id;
    } catch (error) {
      console.error("sqliteJs.openDb: Error opening database", error);
      throw error;
    }
  },

  exec: (id, sql, params) => {
    try {
      console.log("sqliteJs.exec: Executing query", { id, sql, params });
      const db = window._dbs[id];
      if (!db) {
        throw new Error("Database not found: " + id);
      }
      const stmt = db.prepare(sql);
      if (params) stmt.bind(params);
      const rows = [];
      while (stmt.step()) rows.push(stmt.getAsObject());
      stmt.free();
      console.log("sqliteJs.exec: Query returned", rows.length, "rows");
      return rows;
    } catch (error) {
      console.error("sqliteJs.exec: Error executing query", error);
      throw error;
    }
  },

  export: (id) => {
    try {
      console.log("sqliteJs.export: Exporting database", id);
      return window._dbs[id].export();
    } catch (error) {
      console.error("sqliteJs.export: Error exporting database", error);
      throw error;
    }
  },

  close: (id) => {
    try {
      console.log("sqliteJs.close: Closing database", id);
      window._dbs[id].close();
      delete window._dbs[id];
    } catch (error) {
      console.error("sqliteJs.close: Error closing database", error);
      throw error;
    }
  }
};

Step 3: Reference the Interop Script in `index.html`

Blazor WebAssembly apps use wwwroot/index.html as the host page.

Open wwwroot/index.html and add the sql.js interop script before the Blazor script:

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>WASMDemowithBlazorApp</title>
    <base href="/" />
    <link rel="preload" id="webassembly" />
    <link rel="stylesheet" href="lib/bootstrap/dist/css/bootstrap.min.css" />
    <link rel="stylesheet" href="css/app.css" />
    <link rel="icon" type="image/png" href="favicon.png" />
    <link href="WASMDemowithBlazorApp.styles.css" rel="stylesheet" />
    <script type="importmap"></script>
</head>

<body>
    <div id="app">
        <svg class="loading-progress">
            <circle r="40%" cx="50%" cy="50%" />
            <circle r="40%" cx="50%" cy="50%" />
        </svg>
        <div class="loading-progress-text"></div>
    </div>

    <div id="blazor-error-ui">
        An unhandled error has occurred.
        <a href="." class="reload">Reload</a>
        <span class="dismiss">🗙</span>
    </div>

    <!-- sql.js interop -->
    <script src="/sqljs/sqljsInterop.js"></script>

    <!-- Blazor WebAssembly -->
    <script src="_framework/blazor.webassembly#[.{fingerprint}].js"></script>
</body>

</html>

Step 4: Create a C# `SqlJsService` for JS Interop

Now we wrap the JavaScript API with a clean C# service.

Add a new class: Services/SqlJsService.cs:

using System.Text.Json;
using Microsoft.JSInterop;

namespace WASMDemowithBlazorApp.Services;

public class SqlJsService
{
    private readonly IJSRuntime _js;
    private bool _init;

    public SqlJsService(IJSRuntime js)
    {
        _js = js;
    }

    public async Task InitAsync()
    {
        if (_init)
        {
            return;
        }

        await _js.InvokeVoidAsync("sqliteJs.init");
        _init = true;
    }

    public Task<string> OpenAsync(byte[]? bytes = null)
    {
        return _js.InvokeAsync<string>("sqliteJs.openDb", bytes).AsTask();
    }

    public async Task<List<Dictionary<string, object>>> QueryAsync(
        string id,
        string sql,
        object[]? args = null)
    {
        var raw = await _js.InvokeAsync<object>("sqliteJs.exec", id, sql, args);

        // Convert JS objects -> JSON -> Dictionary<string, object>
        return JsonSerializer.Deserialize<List<Dictionary<string, object>>>(
                   JsonSerializer.Serialize(raw))
               ?? new List<Dictionary<string, object>>();
    }

    public Task<byte[]> ExportAsync(string id)
    {
        return _js.InvokeAsync<byte[]>("sqliteJs.export", id).AsTask();
    }

    public Task CloseAsync(string id)
    {
        return _js.InvokeVoidAsync("sqliteJs.close", id).AsTask();
    }
}

using Microsoft.AspNetCore.Components.Web;
using Microsoft.AspNetCore.Components.WebAssembly.Hosting;
using WASMDemowithBlazorApp;
using WASMDemowithBlazorApp.Services;

var builder = WebAssemblyHostBuilder.CreateDefault(args);
builder.RootComponents.Add<App>("#app");
builder.RootComponents.Add<HeadOutlet>("head::after");

builder.Services.AddScoped(sp => new HttpClient
{
    BaseAddress = new Uri(builder.HostEnvironment.BaseAddress)
});

// Register SQL.js service
builder.Services.AddScoped<SqlJsService>();

await builder.Build().RunAsync();

Step 5: Add the Chinook SQLite Database

We'll use the classic Chinook sample database (music store data).

Create a folder:

wwwroot/
  chinook/
    chinook.sqlite

Download Chinook_Sqlite.sqlite from the Chinook GitHub repo and rename it to chinook.sqlite.
Place it under wwwroot/chinook/chinook.sqlite.

This file will be served as a static asset and loaded into memory by the browser.

Step 6: Build the Blazor Page to Query SQLite

Now we create a Blazor component that:

Loads the database file via HttpClient
Opens it with SqlJsService
Executes a SELECT against the Album table
Renders the first 10 albums

Create Pages/Chinook.razor:

@page "/chinook"
@inject Services.SqlJsService Sql
@inject HttpClient Http
@implements IAsyncDisposable

<PageTitle>Chinook Database</PageTitle>

<h1>Chinook Database Demo</h1>

<p>This page demonstrates client-side SQLite using sql.js in Blazor WebAssembly.</p>

@if (rows == null)
{
    <p><em>Loading database...</em></p>
}
else if (errorMessage != null)
{
    <div class="alert alert-danger" role="alert">
        <strong>Error:</strong> @errorMessage
    </div>
}
else
{
    <h3>Albums (First 10)</h3>
    <table class="table">
        <thead>
            <tr>
                <th>Album ID</th>
                <th>Title</th>
            </tr>
        </thead>
        <tbody>
            @foreach (var r in rows)
            {
                <tr>
                    <td>@r["AlbumId"]</td>
                    <td>@r["Name"]</td>
                </tr>
            }
        </tbody>
    </table>
}

@code {
    string? dbId;
    List<Dictionary<string, object>>? rows;
    string? errorMessage;

    protected override async Task OnInitializedAsync()
    {
        try
        {
            Console.WriteLine("Starting SQL initialization...");
            await Sql.InitAsync();
            Console.WriteLine("SQL initialized successfully");

            Console.WriteLine("Fetching database file...");
            var bytes = await Http.GetByteArrayAsync("chinook/chinook.sqlite");
            Console.WriteLine($"Database loaded: {bytes.Length} bytes");

            Console.WriteLine("Opening database...");
            dbId = await Sql.OpenAsync(bytes);
            Console.WriteLine($"Database opened with ID: {dbId}");

            Console.WriteLine("Executing query...");
            rows = await Sql.QueryAsync(
                dbId,
                "SELECT AlbumId, Title AS Name FROM Album LIMIT 10"
            );
            Console.WriteLine($"Query returned {rows.Count} rows");
        }
        catch (Exception ex)
        {
            errorMessage = $"{ex.GetType().Name}: {ex.Message}";
            Console.WriteLine($"Error: {errorMessage}");
            Console.WriteLine($"Stack trace: {ex.StackTrace}");
        }
    }

    public async ValueTask DisposeAsync()
    {
        if (dbId != null)
        {
            try
            {
                await Sql.CloseAsync(dbId);
            }
            catch
            {
                // Ignore dispose errors
            }
        }
    }
}

Finally, add a nav link (optional, but nice) in Layout/NavMenu.razor:

<div class="nav-item px-3">
    <NavLink class="nav-link" href="chinook">
        <span class="bi bi-database" aria-hidden="true"></span> Chinook DB
    </NavLink>
</div>

Step 7: Run and See the Result

Run the Blazor WebAssembly app:

dotnet run

Navigate to:

https://localhost:xxxx/chinook

You should see:

A loading message
Then a table of the first 10 albums from the Album table rendered directly from SQLite in the browser.

No API controller. No EF Core. Just pure WASM + Blazor + sql.js.

What We Learned (and Things to Be Careful About)

While wiring this up, a few important lessons surfaced:

Static file locks during build
- Visual Studio may complain that chinook.sqlite is in use during build if some process has it open.
- If you see IOException: The process cannot access the file ... chinook.sqlite, close any external tools (SQLite browser, etc.) and stop the running dev server before rebuilding.
SQLite table names are case-sensitive here
- The Chinook schema uses Album, not albums.
- A tiny mismatch like FROM albums results in Error: no such table: albums deep in a JS stack trace.
- When troubleshooting, run a quick SELECT name FROM sqlite_master WHERE type='table'; using a local SQLite client to confirm table names.
Blazor + JSInterop error surfacing
- SQL errors show up first in the browser console (JS), then are re-thrown into .NET as JSException.
- Logging in both C# (Console.WriteLine) and JS (console.log, console.error) makes it much easier to trace problems across the boundary.
Disposal still matters in WebAssembly
- Even though everything is in-memory, it's good practice to implement IAsyncDisposable on your Blazor components and close the in-memory databases when the component is torn down.
- This keeps your in-browser resources tidy, especially if you open multiple databases.
Script load order is important
- sqljsInterop.js must load before Blazor starts calling sqliteJs.init.
- Keep the interop <script> tag before _framework/blazor.webassembly*.js in index.html.

These small details are easy to miss when you're new to mixing Blazor, JS interop, and WebAssembly, but they're exactly what make the experience smooth once you know them.

Summary

In this exercise, we:

Integrated sql.js (SQLite on WebAssembly) into a Blazor WebAssembly app.
Created a JavaScript interop layer to load, open, query, export, and close SQLite databases in the browser.
Wrapped that logic in a C# SqlJsService, exposing a clean async API.
Loaded the Chinook sample database from wwwroot, executed a SQL query against the Album table, and rendered results in a Blazor component.
Learned several practical troubleshooting tips for working with Blazor + WebAssembly + JS interop.

With this foundation, you can:

Build offline data explorers
Ship demo apps that "feel" like full-stack but run entirely in the browser
Prototype data-driven features without standing up real infrastructure

Love C# & Blazor WASM!

DEV Community: David Au Yeung

Build a Facial Recognition System with C#, ArcFace ONNX, and OpenCV DNN

Introduction

Table of Contents

Prerequisites

Understanding the Technology

Why Two Models?

1. OpenCV DNN Face Detector (The "Face Finder")

2. ArcFace ONNX (The "Face Recognizer")

What is ArcFace?

The Face Recognition Pipeline

Setting Up the Project

Step 1: Create a New Console Application

Step 2: Install Required NuGet Packages

Step 3: Create Project Folders

Downloading the Models

Model 1: ArcFace ONNX (Face Recognition)

Model 2: OpenCV Face Detection Models

Building the Face Recognition Service

Understanding the Code

Constructor

GetEmbedding() Method

DetectLargestFace() Method

ProcessFaceForArcFace() Method

CosineSimilarity() Method

Creating the Main Application

What This Code Does

How It All Works Together

Step-by-Step Execution Flow

The Math Behind Cosine Similarity

Why Face Detection Matters

Testing Your System

Prepare Test Images

Example Test Setup

Run the Demo

Expected Output

The Journey to Better Accuracy

Iteration 1: Basic ArcFace (No Face Detection)

Iteration 2: Tried FaceRecognitionDotNet (You may retry again!)

Iteration 3: OpenCV DNN + ArcFace (Current Solution)

Key Learnings

Next Steps

Production Enhancements

1. Add a Database

2. Real-Time Webcam Recognition

3. Face Recognition API

4. Multi-Face Support

5. Add Face Alignment

Performance Optimization

Security Considerations

Conclusion

What We Built

Key Takeaways

The Tech Stack

Going Further

Resources

Turn Plain English into Safe, Fast C# Rules with Ollama and Expression Trees

Introduction

What We Are Building

The Golden Rule: AI Writes Data, Not Code

Prerequisites

Step 1: Create a New Console App

Step 2: Project File (Reference)

Step 3: Define the Rule Model (the AST)

Step 4: Teach JSON How to Be Polymorphic

Step 5: The Heart of It - Compile Rules with Expression Trees

⭐ The One Line That Makes the Magic: Expression.Lambda<Func<T, bool>>(body, parameter)

Unpacking it

The payoff: .Compile()

Why I keep calling it "a really good tool"

Bonus: it composes with EF Core

Step 6: Reuse Your Ollama Service (Natural Language → JSON)

Step 7: Give the Model a Schema (So It Stops Guessing)

Step 8: Wire Up the Demo in Program.cs

Step 9: Run It

Why Expression Trees Beat the Alternatives

Why This Is a Fun (and Safe) Experiment

Notes and Limitations

Closing

Step-by-Step Guide: Connect Blazor to Device Camera with JavaScript Interop and Face Recognition Logic

`GetEmbedding()` Method

`DetectLargestFace()` Method

`ProcessFaceForArcFace()` Method

`CosineSimilarity()` Method

⭐ The One Line That Makes the Magic: `Expression.Lambda<Func<T, bool>>(body, parameter)`

The payoff: `.Compile()`

Step 8: Wire Up the Demo in `Program.cs`

Detailed coding (`Components/Pages/Patrol.razor`)

Detailed coding (`wwwroot/js/patrolCamera.js`)

Detailed coding (`Controllers/DetectController.cs`)

Detailed coding (`Services/FaceRecognitionService.cs`) - current demo behavior

Detailed coding (`Data/DbStrategy/*`)

Step 3: Add `Program.cs`

Step 4: Add `Services/DesignMdGenerator.cs`