DEV Community: David Au Yeung

Python has a tool for that. What about .NET?

David Au Yeung — Sun, 11 Oct 2026 13:47:52 +0000

I was scrolling through Facebook when I found a post by She Explores Data about using Python to solve everyday programming problems.

Messy data? There is a library for that.

Need automation? There is a tool for that.

Building an API? Yes, that too.

My brain says: nice.

My .NET brain says: wait, what about us?

Then I generated an infographic, this time about using .NET 10 for problem-solving.

Start with the problem, not the package

Sometimes I open NuGet before I have properly understood the task.

"This package looks useful."
"That one has lots of downloads."

"Maybe I should install both. Just in case."

Now I have more dependencies.

Still the same problem.
(more packages, but you still haven’t solved the original problem:))

What I liked about these graphics is the simple approach: start with what you need to build, then look for a tool that fits.

A little .NET toolbox

Here are some starting points from the .NET graphic, in my own words:

This is a starting list, not an instruction to install everything.

Also, the infographic focuses on .NET 10. If your project targets another version, check the framework requirements and package compatibility first.

Not Python versus .NET

I do not read this as a language competition.

Python has a rich ecosystem, especially for data work and automation. .NET has plenty of options for applications, services, and other workloads too.

The useful question is not:

"Which language wins?"

It is:

"Which tool fits this problem, this project, and this team?"

Sometimes the answer is Python.

Sometimes it is C#.

Sometimes it is a small script, not a whole new architecture.

Inspiration and credit

Inspired by the She Explores Data Facebook post, "24 Python Problems and the Tools That Help Solve Them": https://www.facebook.com/share/p/1GJPGLaMse/

This article shares my own reaction to the Python post and the .NET infographic I created from that inspiration.

Love .NET!

I Love .NET Blazor. Now It Can Build Agentic UI, Not Just Chat Boxes

David Au Yeung — Sat, 03 Oct 2026 10:12:50 +0000

Introduction

I love Blazor so much. I have used it to build more than 10 projects this year.

One thing I enjoy is that I can build interactive web applications with C#. I can reuse familiar types, validation rules, and components instead of switching languages for every part of the application.

So I am happy to see Blazor keep improving, especially for the AI era.

Recently, I read Daniel Roth's Microsoft article, Build Agentic UI with the new Blazor AI components.

My first thought was:

"Nice. But can we build something more useful than another chat box?"

A chat box is useful. However, many applications need more than text replies.

We want the AI to show a tool result as a card. We want it to understand the document we are editing. We want it to suggest changes without quietly replacing our work. And before it performs an important action, we want a real approval button.

That is the idea behind Agentic UI.

In this article, I will explain the new Blazor AI building blocks through a single Blazor demo application. We will look at streaming chat, typed tool cards, frontend actions, human approval, shared state, document review, and a live checklist.

The important part is not that the AI can do everything.

The AI can help with the work. The application defines the rules. The user stays in control.

What Is Agentic UI?

A normal chatbot often follows this flow:

User asks a question
  -> model returns text
  -> application displays the text

An agentic application can go further:

User asks for help
  -> agent reads the current workspace
  -> agent requests an allowed tool
  -> application validates the request
  -> user approves when required
  -> tool returns a result or a state update
  -> Blazor renders the result

For example, "make this recipe vegan" does not have to produce a separate recipe in a chat message. It can update a recipe editor that the user and agent share.

Similarly, "improve this document" does not have to overwrite the document immediately. It can produce a proposed revision with Accept and Reject buttons.

This is still a normal application. We still write the components, define the tools, validate the data, and decide which actions are allowed.

The model does not get permission to run arbitrary C# or generate executable UI code.

What We Are Building

My demo uses one Interactive Server Blazor application.

Browser
  -> Interactive Server Blazor UI
  -> UIAgent and server-side AG-UI client
  -> /agents/{scenario} in the same application
  -> Microsoft Agent Framework
  -> Ollama at localhost:11434
  -> selected cloud model

There is no separate agent server, Aspire host, database, or real calendar integration in this demo.

The eight pages are:

Streaming chat
Backend weather tool rendering
Frontend accent-color tool
Meeting approval
Shared recipe state
Predictive document review
Live plan and activities
Reasoning capability information

The weather and meeting tools are simulated. The plan is a demo checklist, not proof that real-world tasks have been completed.

A Preview Warning Before We Start

The Microsoft article introduces experimental Blazor AI components. This demo targets net11.0 and uses the .NET 11 RC1 SDK.

These APIs can change. This is a learning project, not a production-ready application or a stable API promise.

The versions below are the versions used by this demo. If you read this article later, check package availability and the current Microsoft guidance before starting a new project.

Step 1: Install .NET 11

Install the .NET 11 RC1 SDK, not only the runtime. The SDK is required to restore and build the application.

Use the official .NET download page and select the installer that matches your operating system and architecture. For this Windows workspace, I used Visual Studio 2026 with the ASP.NET and web development workload and preview SDK support enabled.

After installing, open a new terminal:

dotnet --list-sdks
dotnet --version

The demo pins this SDK in the solution root's global.json:

{
  "sdk": {
    "version": "11.0.100-rc.1.26425.128",
    "rollForward": "disable",
    "allowPrerelease": true
  }
}

This pin makes everyone use the same SDK. Run dotnet --version from the repository folder to check it. Because rollForward is disabled, another .NET 11 preview is not enough: install the exact version shown above to reproduce this demo.

The application project targets:

<TargetFramework>net11.0</TargetFramework>

If Visual Studio does not recognize the SDK, enable preview SDK support in its settings and restart the IDE.

Step 2: Add the AI Building Blocks

The demo needs packages for three jobs: showing the UI, running tools, and communicating with the model. These references are already in BlazorApp1_Demo.csproj:

<ItemGroup>
  <PackageReference Include="Microsoft.AspNetCore.Components.AI" Version="0.1.0-preview.1.26466.103" />
  <PackageReference Include="Microsoft.Extensions.AI" Version="10.10.0" />
  <PackageReference Include="OllamaSharp" Version="5.5.0" />
  <PackageReference Include="Microsoft.Agents.AI.Hosting.AGUI.AspNetCore" Version="1.23.0-preview.260928.1" />
  <PackageReference Include="AGUI.Client" Version="1.0.0" />
  <PackageReference Include="Markdig" Version="0.44.0" />
</ItemGroup>

You do not need to learn every package at once:

UI: Blazor AI components provide the conversation and tool cards. Markdig helps the demo process Markdown for safe display.
Agent and tools: Microsoft.Extensions.AI provides IChatClient, the interface for sending messages to a model. Microsoft Agent Framework coordinates the agent and its tools.
Communication: OllamaSharp connects to Ollama. AG-UI carries messages, tool results, and state updates between the agent and the UI.

The Microsoft article's quick-start command uses --prerelease. This project pins exact versions so the example is easier to reproduce.

The AI package also supplies a stylesheet. In Components/App.razor, the demo includes:

<link rel="stylesheet" href="@Assets["_content/Microsoft.AspNetCore.Components.AI/ai-chat.css"]" />

Without the package styles, the components may not look the way you expect.

Step 3: Configure Ollama

This demo uses gemma4:31b-cloud through Ollama. The Ollama service runs locally, but this model runs in the cloud. You need an account and an internet connection; prompts and workspace content are sent to that service, and usage may have quotas or costs.

Install and start Ollama, then sign in and prepare the model:

ollama signin
ollama pull gemma4:31b-cloud
ollama show gemma4:31b-cloud

This demo uses exactly gemma4:31b-cloud. It does not silently switch to another model.

The Ollama section in appsettings.json is:

"Ollama": {
  "Endpoint": "http://localhost:11434",
  "Model": "gemma4:31b-cloud",
  "TimeoutSeconds": 120,
  "MaxToolIterations": 8,
  "AgentBaseAddress": "http://localhost:5052"
}

This is a section inside the full JSON configuration file, not a standalone JSON document.

Do not mix up the two addresses:

Endpoint points to Ollama, on port 11434.
AgentBaseAddress points to this Blazor app, on port 5052, where its agent endpoints are hosted.

Do not put private documents into this demo. Keep authentication out of source control and out of the browser.

Step 4: Start With `ChatPage` and `UIAgent`

Start with two building blocks: ChatPage displays the conversation, and UIAgent connects it to a chat client.

For a standalone chat, the markup is small:

<ChatPage Agent="_agent" Placeholder="Ask the agent…" />

ChatPage provides the input and streamed messages, so we do not have to build them from scratch. Our demo uses a typed agent to share workspace data as well:

private UIAgent<WorkspaceState>? _agent;

WorkspaceState holds the recipe, document, checklist, and their revision numbers.

Here is a shortened excerpt of the setup:

_agent = new UIAgent<WorkspaceState>(_client, options =>
{
    options.AddGeneratedToolBlocks();
}, _session.Snapshot());

AddGeneratedToolBlocks enables the tool cards we will use next, and _session.Snapshot() supplies the initial workspace state. The full setup is in Components/Pages/Demo.razor.

Sharing the Conversation With a Toolbar

Our demo also has Try example, Cancel, and Reset controls outside the message list. To make those controls work with the displayed conversation, we use the lower-level components instead of ChatPage:

<AgentBoundary Agent="_agent" @key="_agent">
    <ConversationScope ContextChanged="ObserveContext">
        @* The toolbar and scenario editors are also inside this scope. *@
        <section class="demo-chat sc-ai-root">
            @* The full page also has a conversation heading and role key. *@
            <MessageList>
                @* Register the typed BlockRenderer components here. *@
            </MessageList>
            <div class="demo-chat-composer">
                <MessageInput Placeholder="Write a message to the agent…" />
            </div>
        </section>
    </ConversationScope>
</AgentBoundary>

Three details matter here:

AgentBoundary provides one AgentContext: the shared conversation state for messages, status, and cancellation. ChatPage normally creates this boundary for you.
ConversationScope is a small demo helper, not a package component. It gives the toolbar access to that same context. Do not create a separate context for the toolbar, or its requests will belong to a different conversation. @key gives Reset a fresh boundary when the agent changes.
sc-ai-root applies the package's styling variables when using MessageList and MessageInput directly. demo.css then customizes the bubbles and layout.

The result is one conversation with clearly labeled user messages, agent replies, and tool cards.

How a Message Reaches Ollama

In Program.cs, two demo extension methods register the provider and agent services:

builder.Services.AddDemoOllama(builder.Configuration);
builder.Services.AddDemoAgents();

AddDemoOllama configures the Ollama chat client. AddDemoAgents registers the agents and tools; app.MapDemoAgents() exposes their /agents/{scenario} endpoints. Registration alone does not send a prompt or test connectivity.

When you send a message or click Try example:

UIAgent sends the conversation request to the app's agent endpoint through AG-UI.
Microsoft Agent Framework calls Ollama, which contacts the selected cloud model.
If the model requests a tool, the application validates it and asks for approval when required.
Text, tool results, and state updates stream back to the Blazor UI.

Because this is Interactive Server Blazor, the AG-UI client and provider calls run on the server. The browser does not connect directly to Ollama. The following steps show how the UI handles each kind of result.

Step 5: Turn a Tool Result Into a Typed Card

Instead of asking the model to format a weather report, we can display a C# tool result in a card.

Try this on /demo/weather:

"Compare the demo weather in Seattle and Paris."

The readings are simulated, not live forecasts. Here is how the result reaches the card.

Register the Tool

First, expose the backend function as a tool the model can request:

AIFunctionFactory.Create(
    GetWeather,
    name: "get_weather",
    description: "Get deterministic SIMULATED demo weather for a city. Not a real forecast.")

The application validates the arguments, runs the function, and returns a typed result. The model requests the work; application code performs it.

Map the Result to a Block

In Components/ToolBlocks.cs, a tool block connects the request and result to properties the UI can render:

using BlazorApp1_Demo.AI;
using Microsoft.AspNetCore.Components.AI;

namespace BlazorApp1_Demo.Components;

[ToolBlock("get_weather")]
public partial class WeatherBlock : FunctionInvocationContentBlock
{
    [ToolParameter(Name = "location")]
    public string? Location { get; set; }

    [ToolResult]
    public WeatherResult? Weather { get; set; }
}

Here is what these attributes mean:

ToolBlock connects the block to the tool name.
ToolParameter maps the function argument to a C# property.
ToolResult maps the returned data to a typed result property.
The partial class works with the package's generated mapping support.

The result travels through AG-UI as JSON. Explicit JSON property names keep the backend result and the generated block mapper in agreement:

public sealed record WeatherResult(
    [property: System.Text.Json.Serialization.JsonPropertyName("location")] string Location,
    [property: System.Text.Json.Serialization.JsonPropertyName("temperatureC")] int TemperatureC,
    [property: System.Text.Json.Serialization.JsonPropertyName("conditions")] string Conditions,
    [property: System.Text.Json.Serialization.JsonPropertyName("source")] string Source = "Simulated demo data; not a live forecast");

These names matter because the preview mapper does not automatically use the backend's JSON settings. The card reads the tool result, not the assistant's description of it.

Render the Card

Place a renderer inside MessageList. This shortened example handles loading, success, and failure:

<BlockRenderer TBlock="WeatherBlock" Context="weather">
    <section class="tool-card">
        <h3>Demo weather · @weather.Location</h3>
        @if (!weather.HasResult)
        {
            <p>Fetching simulated weather…</p>
        }
        else if (weather.Weather is { } result)
        {
            <p>@result.TemperatureC °C · @result.Conditions</p>
        }
        else
        {
            <p>The demo weather tool failed.</p>
        }
    </section>
</BlockRenderer>

This is normal Razor markup: we control the layout and messages. The AI chooses an allowed tool; it does not generate executable UI code.

Step 6: Let a Tool Change the Blazor UI

Tools can change the UI too. On /demo/accent, try:

"Change the accent color to teal."

Here, a frontend tool means a function owned by the UI component. In Interactive Server Blazor it still runs on the server, through the user's Blazor circuit-not as model-generated JavaScript.

The accent scenario registers SetAccent as set_accent_color. Its implementation is:

private async Task<string> SetAccent(string color, CancellationToken cancellationToken)
{
    cancellationToken.ThrowIfCancellationRequested();
    var selected = AccentPalette.Validate(color);
    _session?.RecordTool("set_accent_color", cancellationToken);
    await InvokeAsync(() => { _accent = selected; StateHasChanged(); });
    return $"Accent set to {color} on the Blazor UI thread.";
}

The key points are simple:

Validate the requested color before changing anything.
Accept only named colors from AccentPalette, such as teal, blue, or purple. Raw CSS and hex values are not allowed.
Use InvokeAsync to update the component through Blazor's dispatcher.
Return a result after the change happens.

The demo's FunctionInvokingChatClient executes the registered function and limits tool iterations. Registering the function makes it available; this client handles its invocation.

No arbitrary CSS. No model-generated script. Just a small function with clear rules.

Step 7: Ask the Human Before an Important Action

Some actions should not happen just because a model requested them.

The meeting tool is wrapped with ApprovalRequiredAIFunction:

new ApprovalRequiredAIFunction(
    AIFunctionFactory.Create(
        BookMeeting,
        name: "book_meeting",
        description: "Book a SIMULATED demo meeting, only after user approval. Provide title and ISO 8601 time with Z or timezone offset. No real calendar is accessed."))

The UI renders a FunctionApprovalBlock with the meeting title, time, and two choices:

Approve simulated booking allows the matching request to proceed.
Reject declines the request without booking it.

Typing "ok" in chat does not replace approval. The server checks consent for the exact request, rejects expired or canceled approvals, and prevents duplicate execution. Approvals expire after two minutes. These checks live in AI/MeetingApprovals.cs, not just in the buttons.

This is a simulated booking. No real calendar is accessed.

Try this on /demo/approval:

"Book a demo meeting called Review at 2026-12-01T14:00:00Z."

Use a future ISO 8601 time when trying this later.

Step 8: Share State With the Agent

A conversation is more useful when the agent can work with the recipe in your editor, rather than return an unrelated recipe in chat.

On /demo/recipe, edit the title or ingredients, then ask:

"Make the current recipe vegan, preserving my edits."

The tool returns a complete WorkspaceState. The endpoint sends it to the UI as a snapshot: the state at that point in time.

endpoint.WithMetadata(
    new AGUIStreamOptions()
        .MapResultAsStateSnapshot("generate_recipe"));

The UI uses that snapshot to update its typed state. To protect your edits, the recipe also has a revision number, which increases when it changes. An agent update must match the current revision:

Agent reads recipe revision 3
  -> user edits the recipe to revision 4
  -> agent returns a change based on revision 3
  -> application rejects the stale update

Without that check, a slow AI response could overwrite a newer user edit.

Recipe text is supplied as data, not instructions. Text inside an ingredient or title cannot grant the agent permission to change the application's rules.

Step 9: Preview a Document Change Before Saving It

Unlike the recipe editor, the document scenario lets you review a proposed change before applying it.

On /demo/document, try:

"Make this document clearer and more concise."

The review flow is:

Current document
  -> agent proposes a revision
  -> user compares the original, proposal, and highlighted differences
  -> user accepts or rejects
  -> application commits only an accepted, current proposal

The document scenario registers a UI action:

options.RegisterUIAction(
    AIFunctionFactory.Create(
        ApplyDocumentDecision,
        name: "propose_document",
        description: "Propose a complete document for explicit user review. Supply expectedRevision from current documentRevision; do not set accepted yourself."));

A UI action produces a UIActionBlock, where the user can accept or reject the proposal. Predictive state means showing the suggested content without replacing the saved workspace version yet. Acceptance checks the revision again before applying it.

The preview receives the original and proposed text through Razor expressions:

<DocumentPreview Before="@(_session!.Snapshot().Document)" After="@(proposal.Document)" />

Keep the @ expressions: these are string parameters, so omitting @ would display the expression names as literal text.

Editing the committed document while a proposal is pending invalidates that review. Canceling or resetting also rejects unresolved proposals.

This is my favorite part of the demo:

AI can suggest a better version without taking ownership of my document.

Step 10: Show a Live Plan and Real Tool Activity

The plan scenario turns an agent's checklist into visible, editable UI rather than leaving it buried in a chat reply.

Try this on /demo/plan:

"Create a three-step demo plan and mark the first step completed."

Two tools drive the updates through AG-UI:

create_plan returns a snapshot containing the complete checklist.
update_plan_step returns a delta that changes one step's status.

Each row shows a checkbox, a description, and a status: Pending, In progress, Completed, or Failed. You can also change checklist items yourself.

To keep updates consistent, the server allows only one plan tool call per model response. Extra calls are deferred so the model can review fresh state before deciding the next change. Revision checks reject stale writes instead of letting them overwrite newer user edits.

The activity panel records actual tool invocations-not the model's private reasoning. A deferred call is not shown as executed.

Checklist progress is demo state, not proof of real-world work. Marking a step completed does not mean a trip was booked or an external task was performed.

What About Reasoning Summaries?

The Microsoft article also discusses reasoning summaries when the provider supports them.

This demo's Ollama adapter/model contract does not expose a verified reasoning-summary channel. The reasoning page says that clearly instead of making up a summary.

Raw model thinking is filtered and is not shown as an activity feed.

These are different things:

A tool activity is an actual application event.
A supported reasoning summary is provider-supplied summary content.
Raw internal thinking is not something this demo displays.

Not every provider supports every feature. A useful UI should explain that limit honestly.

Step 11: Run the Demo

With the pinned SDK installed and Ollama configured, run these commands from the repository root:

dotnet restore BlazorApp1_Demo.slnx
dotnet build BlazorApp1_Demo.slnx
dotnet run --project BlazorApp1_Demo/BlazorApp1_Demo.csproj --launch-profile http

Then:

Open http://localhost:5052 and choose a scenario.
Use Check Ollama to inspect model metadata and tool capability. This is not an inference test or a guarantee that a request will succeed.
When you are ready to send content to the cloud model, click Try example or type your own prompt.

Prefer Visual Studio? Select BlazorApp1_Demo as the startup project and use the http launch profile. If you change the app's port, update Ollama:AgentBaseAddress to match.

Useful controls to try:

Try example to send the page's sample request
Cancel to stop an active turn
Retry after an error
Reset scenario to start a new isolated session

If something fails, start with the relevant check:

Build fails: confirm that dotnet --version in the repository matches global.json.
Model request fails: check that Ollama is running, you are signed in, and gemma4:31b-cloud is available to your account.
Agent endpoint is unreachable: confirm that AgentBaseAddress matches the running app's address.

Limitations and Next Steps

This is an experimental local demo.

Before building a production application, I would add:

Real user authentication and per-user authorization
Durable conversation and workspace storage
Auditing for sensitive actions
Production secret management
Browser, keyboard, screen-reader, and reconnection tests
Monitoring and model usage controls
A deployment and security review

Final Thoughts

I already liked Blazor because it lets me build interactive applications with C#.

These new AI components give me another reason to stay excited about it.

The useful change is not simply putting a chat box on a page. It is connecting conversation to a real workspace with typed results, visible progress, shared state, and clear user decisions.

My preferred flow is:

AI suggests
  -> application validates
  -> user reviews when needed
  -> allowed tool executes
  -> Blazor shows the result

More help from AI. Less guessing about what it actually did.

And when an important change needs approval, the final decision still belongs to the user.

References

Daniel Roth, Microsoft .NET Blog: Build Agentic UI with the new Blazor AI components
Official .NET 11 download page

This article is my practical walkthrough of the local demo, inspired by Microsoft's introduction.

Love C# & AI!

Do you have "Monthly Limit Anxiety" like me?

David Au Yeung — Wed, 30 Sep 2026 15:25:48 +0000

Every time I finish a task, I pretend to be calm, professional, and focused.

Then, like clockwork, I check the quota bar again.

It doesn't like the progress bar, I don't want it to grow even a bit.
I care about every move it makes.
I care about every instruction I send.

Tonight's screenshot says 96.5% used.

My brain says: danger.
My brain says: That move isn't good enough, like I'm playing chess against my own quota bar.

At this point, I am not tracking project progress.

I am tracking survival.

But here is the comedy twist:

It is 30/9, 22:45.
Tomorrow is 1 Oct.

So yes, I am at 96%.

And yes, I am suddenly the most peaceful person alive,

because next morning is basically a software patch for my emotions.

Token reset is coming.

Panic deprecated.

I call it Monthly Limit Anxiety.

I Stopped Asking Copilot to Format My 100-Page Markdown Reports. Here Is the Deterministic C# Fix

David Au Yeung — Sat, 08 Aug 2026 08:11:31 +0000

Introduction

Recently, I used a search AI to research a topic and it returned a result of more than 100 pages.

That sounds useful at first. But after the research is done, the next problem is very practical: how do we turn that large Markdown result into a proper Word document that people can read, review, edit, and share?

My first thought was simple:

"I will give the Markdown to Microsoft 365 Copilot and ask it to convert the content into a nicely formatted Word document."

It did not go as planned.

It converted roughly the first two pages, then confidently said the task was complete. Lol.

Even if a tool successfully converts the whole document, there is another problem: the output style may not match previous project documents. Headings look different. Tables get unexpected colors. Fonts drift. The new report looks like it came from a different project.

So I wrote a small local service instead.

The goal is intentionally boring, and that is exactly why it is useful:

Markdown file -> deterministic C# conversion -> consistently formatted .docx

No prompt. No model. No token cost. No partial response because an AI decided that two pages were enough. And most importantly, the document style is controlled in code.

This article walks through the MarkdownToWordService in a .NET 8 console project. It converts Markdown-like text files into Word documents and gives us style options for headings, body text, code blocks, lists, and tables.

What We Are Building

Search AI produces a large Markdown report
  -> save it as Markdown/Example.txt
  -> MarkdownToWordService
  -> parse headings, lists, tables, emphasis, and code blocks
  -> apply deterministic Word formatting
  -> Example.docx

The important difference is this:

An AI decides how much to process and how to format it
A local service processes every line in the input file
Formatting is defined by MarkdownToWordStyleOptions
The same input and style options give the same output
The conversion costs zero AI tokens

The Demo File: `Markdown/Example.txt`

The project includes Markdown/Example.txt as a small input document. It contains the elements that the service understands:

headings
bold and italic text
inline code
numbered and bullet lists
a Markdown table
a horizontal rule
a fenced C# code block

For example, this section from Example.txt:

| Setting | Demo Value | Purpose |
|---|---|---|
| Input file | Example.txt | Markdown source document |
| Output file | Example.docx | Generated Word document |
| AI tokens | 0 | Conversion is deterministic and local |

becomes a real Word table. It does not remain a group of pipe characters.

This makes Example.txt a useful smoke test whenever the conversion service changes.

Prerequisites

Visual Studio or VS Code
.NET 8 SDK
A console application
The Open XML SDK package

Add the package:

dotnet add package DocumentFormat.OpenXml

The conversion is completely local. There is no Ollama server, cloud endpoint, API key, model download, or token budget required.

Step 1: Define the Conversion Options

The service accepts input, output, and document-style configuration through MarkdownToWordOptions.

public sealed class MarkdownToWordOptions
{
    public string? InputDirectory { get; init; }
    public string? FileName { get; init; }
    public string? OutputDirectory { get; init; }
    public MarkdownToWordStyleOptions Style { get; init; } = new();
}

This is more useful than putting file paths and formatting values directly inside the converter:

the service can process a different report without a code change;
callers can choose an output directory;
style decisions are explicit and versionable;
the service still has sensible defaults for normal use.

The default input directory is the project’s Markdown folder. The console app currently uses Example.txt as the default file.

Step 2: Keep the Style in One Place

The key type is MarkdownToWordStyleOptions.

public sealed class MarkdownToWordStyleOptions
{
    public string BodyFontName { get; init; } = "Aptos";
    public int BodyFontSizeHalfPoints { get; init; } = 22;

    public string TitleColorHex { get; init; } = "156082";
    public int TitleFontSizeHalfPoints { get; init; } = 56;

    public string Heading2ColorHex { get; init; } = "404040";
    public int Heading2FontSizeHalfPoints { get; init; } = 28;

    public string Heading3ColorHex { get; init; } = "0E2841";
    public int Heading3FontSizeHalfPoints { get; init; } = 24;

    public string TableFontName { get; init; } = "Times New Roman";
    public bool ShadeTableHeader { get; init; }
    public bool BoldTableHeader { get; init; }
}

A small Open XML detail: Word stores font sizes in half-points.

22 means 11 pt
24 means 12 pt
28 means 14 pt
56 means 28 pt

Once the style is represented as data, it becomes easy to keep every generated report consistent.

Step 3: Use an Existing Document as the Formatting Reference

In my case, I already had an existing Word specification document with the desired appearance.

Instead of guessing at a new style, I inspected its Open XML definitions. The primary table format turned out to be much simpler than it looked:

Word TableGrid
thin borders
Times New Roman table text
no shaded header row
no bold header row
consistent paragraph spacing and cell margins

That is a useful lesson for document automation:

The best default style is often the one your readers already recognize.

A report should look as if it belongs with the rest of the project documentation.

Step 4: Convert the Markdown File

Calling the service is intentionally small:

using MyPlaygroundApp.Services.MarkdownToWord;

var service = new MarkdownToWordService();

string outputFile = await service.ConvertAsync(new MarkdownToWordOptions
{
    FileName = "Example.txt"
});

Console.WriteLine($"Word file created: {outputFile}");

The service reads Markdown/Example.txt, creates the output directory if required, and writes Example.docx.

You can also override all paths:

string outputFile = await service.ConvertAsync(new MarkdownToWordOptions
{
    InputDirectory = @"C:\Reports\Markdown",
    FileName = "Search-AI-Research-Report.txt",
    OutputDirectory = @"C:\Reports\Word"
});

Step 5: What the Parser Converts

This is not intended to be a full CommonMark implementation. It is a focused document converter for the Markdown patterns that appear in technical reports.

Markdown input	Word output
`# Title`	title-level paragraph
`## Section`	second-level heading
`### Detail`	third-level heading
`important`	bold run
`emphasis`	italic run
`code`	monospace run
`- item`	indented bullet paragraph
`1. item`	indented list paragraph
`---`	horizontal rule
fenced code block	monospace code paragraphs
pipe-delimited table	Word `TableGrid` table

The service processes the input line by line. That may sound simple, but it is exactly what makes it predictable for large reports.

Step 6: Run It

dotnet run

The result looks like this:

A Word About Tables

Tables were the most obvious style mismatch in the first version of the service.

A common generated-document table is visually loud:

blue header background;
bold header text;
custom font;
different border rules;
different spacing from the rest of the document.

That can look fine in isolation. But it does not necessarily match an existing report template.

The updated table renderer uses the reference document’s plain TableGrid approach by default. Custom behavior is still available when needed:

Style = new MarkdownToWordStyleOptions
{
    TableFontName = "Times New Roman",
    ShadeTableHeader = true,
    TableHeaderFillHex = "D9EAF7",
    BoldTableHeader = true
}

The point is not that unshaded tables are always better. The point is that the choice belongs to your document standard, not to a model making a stylistic guess.

Why This Saves More Than Tokens

The obvious benefit is cost.

A local Open XML conversion has no per-page or per-token usage fee. That matters when a search AI produces a long research report and you need to repeat the workflow regularly.

But the more important benefits are operational:

Completeness - every line is processed; there is no model response cutoff.
Repeatability - run the same file twice and get the same document structure.
Consistency - style options keep reports aligned with prior documents.
Traceability - the source Markdown and conversion settings can be checked into version control.
Privacy - the document does not need to leave the machine for formatting.
Control - changes to style are code changes, not prompt experiments.

AI is excellent for research and drafting. Formatting a long, known document into a fixed corporate style is usually a deterministic automation problem.

A Practical Workflow for Long AI Research Results

Here is the workflow I now prefer:

Use search AI to research and draft the initial material.
Save or clean the result as a Markdown or text file.
Put the file in the project Markdown folder.
Run MarkdownToWordService.
Review the generated .docx as a normal Word document.
Keep the Markdown source and the final Word file together with the project.

This keeps AI where it adds the most value - discovering and drafting information - and keeps document production in a deterministic local service.

Limitations and Next Steps

The current service is deliberately lightweight. It supports the structures needed for the project examples, but it is not a complete Markdown engine.

Useful future upgrades could include:

nested lists and true Word numbering definitions;
links and bookmarks;
images;
page headers, footers, and page numbers;
a table of contents;
block quotes;
richer table alignment and column-width rules;
importing a Word template directly instead of configuring styles in code.

For many internal reports, though, headings, paragraphs, lists, tables, code blocks, and consistent fonts already solve most of the real problem.

Final Thoughts

The funny part of this experiment is that it started because an AI said it had finished converting a huge document after handling about two pages.

The useful part is the conclusion:

Use AI to help create the content. Use deterministic code to produce the document.

The result is cheaper, repeatable, and much easier to keep visually consistent with previous reports.

And when the next 100-page search result arrives, Example.txt is there as the smallest possible reminder that the workflow is just:

Markdown in -> local C# service -> consistent Word document out

No missing 98 pages. No formatting lottery. No token bill for a task that should have been a reliable file conversion in the first place.

Complete `MarkdownToWordService` Source

The following is the complete current implementation from Services/MarkdownToWord/MarkdownToWordService.cs, including its options types. Readers can copy it into a .NET 8 project after adding the DocumentFormat.OpenXml package.

using DocumentFormat.OpenXml;
using DocumentFormat.OpenXml.Packaging;
using DocumentFormat.OpenXml.Wordprocessing;
using System.Text.RegularExpressions;

namespace MyPlaygroundApp.Services.MarkdownToWord;

public sealed class MarkdownToWordOptions
{
    public string? InputDirectory { get; init; }
    public string? FileName { get; init; }
    public string? OutputDirectory { get; init; }
    public MarkdownToWordStyleOptions Style { get; init; } = new();
}

public sealed class MarkdownToWordStyleOptions
{
    public string BodyFontName { get; init; } = "Aptos";
    public int BodyFontSizeHalfPoints { get; init; } = 22;
    public string TitleColorHex { get; init; } = "156082";
    public int TitleFontSizeHalfPoints { get; init; } = 56;
    public string Heading2ColorHex { get; init; } = "404040";
    public int Heading2FontSizeHalfPoints { get; init; } = 28;
    public string Heading3ColorHex { get; init; } = "0E2841";
    public int Heading3FontSizeHalfPoints { get; init; } = 24;
    public string CodeFontName { get; init; } = "Consolas";
    public int CodeFontSizeHalfPoints { get; init; } = 20;
    public string TableFontName { get; init; } = "Times New Roman";
    public int TableLineSpacingTwips { get; init; } = 276;
    public int TableParagraphSpacingAfterTwips { get; init; } = 200;
    public int TableCellHorizontalMarginTwips { get; init; } = 108;
    public bool ShadeTableHeader { get; init; }
    public string TableHeaderFillHex { get; init; } = "FFFFFF";
    public bool BoldTableHeader { get; init; }
    public int ListIndentTwips { get; init; } = 720;
}

public sealed class MarkdownToWordService
{
    private const string DefaultFileName = "Example.txt";

    public async Task<string> ConvertAsync(MarkdownToWordOptions? options = null, CancellationToken cancellationToken = default)
    {
        string projectRoot = ResolveProjectRoot();
        string inputDirectory = string.IsNullOrWhiteSpace(options?.InputDirectory)
            ? Path.Combine(projectRoot, "Markdown")
            : options!.InputDirectory!;

        string fileName = string.IsNullOrWhiteSpace(options?.FileName)
            ? DefaultFileName
            : options!.FileName!;

        string outputDirectory = string.IsNullOrWhiteSpace(options?.OutputDirectory)
            //? @"C:\Downloads"
            ? Path.Combine(projectRoot, "Markdown")
            : options!.OutputDirectory!;

        string inputFilePath = Path.Combine(inputDirectory, fileName);
        if (!File.Exists(inputFilePath))
        {
            throw new FileNotFoundException($"Markdown file was not found: {inputFilePath}", inputFilePath);
        }

        Directory.CreateDirectory(outputDirectory);

        string markdown = await File.ReadAllTextAsync(inputFilePath, cancellationToken);
        string outputFilePath = Path.Combine(outputDirectory, $"{Path.GetFileNameWithoutExtension(fileName)}.docx");

        CreateWordDocument(markdown, outputFilePath, options?.Style ?? new MarkdownToWordStyleOptions());

        return outputFilePath;
    }

    private static void CreateWordDocument(string markdown, string outputPath, MarkdownToWordStyleOptions style)
    {
        using WordprocessingDocument wordDocument = WordprocessingDocument.Create(outputPath, WordprocessingDocumentType.Document);

        MainDocumentPart mainPart = wordDocument.AddMainDocumentPart();
        mainPart.Document = new Document();
        Body body = new();

        var lines = markdown.Replace("\r\n", "\n").Split('\n');
        bool inFence = false;

        for (int i = 0; i < lines.Length; i++)
        {
            string rawLine = lines[i].TrimEnd();
            string line = rawLine.TrimStart();

            if (line.StartsWith("```
{% endraw %}
", StringComparison.Ordinal))
            {
                inFence = !inFence;
                body.Append(CreateCodeParagraph(inFence ? "[CODE BLOCK START]" : "[CODE BLOCK END]", style));
                continue;
            }

            if (inFence)
            {
                body.Append(CreateCodeParagraph(rawLine, style));
                continue;
            }

            if (string.IsNullOrWhiteSpace(line))
            {
                body.Append(new Paragraph());
                continue;
            }

            if (IsHorizontalRule(line))
            {
                body.Append(CreateHorizontalRuleParagraph());
                continue;
            }

            if (TryParseTable(lines, ref i, body, style))
            {
                continue;
            }

            if (IsHeading(line, out string headingText, out int headingLevel))
            {
                body.Append(CreateHeadingParagraph(headingText, headingLevel, style));
                continue;
            }

            if (TryParseListItem(line, out string listText, out bool isNumbered))
            {
                body.Append(CreateListParagraph(listText, isNumbered, style));
                continue;
            }

            body.Append(CreateParagraphWithInlineFormatting(line, style));
        }

        mainPart.Document.Append(body);
        mainPart.Document.Save();
    }

    private static bool IsHeading(string line, out string headingText, out int headingLevel)
    {
        headingText = string.Empty;
        headingLevel = 0;

        var match = Regex.Match(line, @"^(#{1,6})\s+(.*)$");
        if (!match.Success)
        {
            return false;
        }

        headingLevel = match.Groups[1].Value.Length;
        headingText = match.Groups[2].Value.Trim();
        return true;
    }

    private static bool IsHorizontalRule(string line)
    {
        string compact = line.Replace(" ", string.Empty).Replace("\t", string.Empty);
        return compact.Length >= 3
               && (compact.All(c => c == '-')
                   || compact.All(c => c == '_')
                   || compact.All(c => c == '*'));
    }

    private static bool TryParseListItem(string line, out string text, out bool isNumbered)
    {
        text = string.Empty;
        isNumbered = false;

        var bullet = Regex.Match(line, @"^[-*+]\s+(.*)$");
        if (bullet.Success)
        {
            text = bullet.Groups[1].Value.Trim();
            return true;
        }

        var numbered = Regex.Match(line, @"^\d+\.\s+(.*)$");
        if (numbered.Success)
        {
            isNumbered = true;
            text = numbered.Groups[1].Value.Trim();
            return true;
        }

        return false;
    }

    private static bool TryParseTable(string[] lines, ref int currentIndex, Body body, MarkdownToWordStyleOptions style)
    {
        if (currentIndex + 1 >= lines.Length)
        {
            return false;
        }

        string headerLine = lines[currentIndex].Trim();
        string separatorLine = lines[currentIndex + 1].Trim();

        if (!headerLine.StartsWith('|') || !headerLine.EndsWith('|'))
        {
            return false;
        }

        if (!Regex.IsMatch(separatorLine, @"^\|\s*:?-+\s*(\|\s*:?-+\s*)+\|$"))
        {
            return false;
        }

        var tableRows = new List<List<string>>
        {
            ParseTableRow(headerLine)
        };

        int rowIndex = currentIndex + 2;
        while (rowIndex < lines.Length)
        {
            string candidate = lines[rowIndex].Trim();
            if (!candidate.StartsWith('|') || !candidate.EndsWith('|'))
            {
                break;
            }

            tableRows.Add(ParseTableRow(candidate));
            rowIndex++;
        }

        body.Append(CreateTable(tableRows, style));
        currentIndex = rowIndex - 1;
        return true;
    }

    private static List<string> ParseTableRow(string line)
    {
        return line.Trim()
            .Trim('|')
            .Split('|')
            .Select(cell => cell.Trim())
            .ToList();
    }

    private static Table CreateTable(List<List<string>> rows, MarkdownToWordStyleOptions style)
    {
        var table = new Table();
        table.Append(new TableProperties(
            new TableStyle { Val = "TableGrid" },
            new TableWidth { Width = "0", Type = TableWidthUnitValues.Auto },
            new TableLook { Val = "04A0", FirstRow = true, FirstColumn = true, NoHorizontalBand = false, NoVerticalBand = true },
            new TableBorders(
                new TopBorder { Val = BorderValues.Single, Size = 4 },
                new BottomBorder { Val = BorderValues.Single, Size = 4 },
                new LeftBorder { Val = BorderValues.Single, Size = 4 },
                new RightBorder { Val = BorderValues.Single, Size = 4 },
                new InsideHorizontalBorder { Val = BorderValues.Single, Size = 4 },
                new InsideVerticalBorder { Val = BorderValues.Single, Size = 4 }),
            new TableCellMarginDefault(
                new LeftMargin { Width = style.TableCellHorizontalMarginTwips.ToString(), Type = TableWidthUnitValues.Dxa },
                new RightMargin { Width = style.TableCellHorizontalMarginTwips.ToString(), Type = TableWidthUnitValues.Dxa })));

        for (int r = 0; r < rows.Count; r++)
        {
            var row = new TableRow();
            foreach (string cell in rows[r])
            {
                var cellParagraph = CreateTableParagraph(style);
                AddInlineRuns(
                    cellParagraph,
                    cell,
                    style,
                    r == 0 && style.BoldTableHeader ? new RunProperties(new Bold()) : null,
                    style.TableFontName);

                row.Append(new TableCell(
                    new TableCellProperties(
                        new Shading
                        {
                            Val = ShadingPatternValues.Clear,
                            Fill = r == 0 && style.ShadeTableHeader ? style.TableHeaderFillHex : "FFFFFF"
                        }),
                    cellParagraph));
            }

            table.Append(row);
        }

        return table;
    }

    private static Paragraph CreateTableParagraph(MarkdownToWordStyleOptions style)
    {
        return new Paragraph(new ParagraphProperties(
            new SpacingBetweenLines
            {
                After = style.TableParagraphSpacingAfterTwips.ToString(),
                Line = style.TableLineSpacingTwips.ToString(),
                LineRule = LineSpacingRuleValues.Auto
            },
            new RunProperties(
                new RunFonts { Ascii = style.TableFontName, HighAnsi = style.TableFontName },
                new FontSize { Val = style.BodyFontSizeHalfPoints.ToString() })));
    }

    private static Paragraph CreateHeadingParagraph(string text, int headingLevel, MarkdownToWordStyleOptions style)
    {
        var paragraph = new Paragraph();
        int fontSize = headingLevel == 1 ? style.TitleFontSizeHalfPoints : headingLevel == 2 ? style.Heading2FontSizeHalfPoints : style.Heading3FontSizeHalfPoints;
        string color = headingLevel == 1 ? style.TitleColorHex : headingLevel == 2 ? style.Heading2ColorHex : style.Heading3ColorHex;
        paragraph.ParagraphProperties = new ParagraphProperties(new SpacingBetweenLines { Before = headingLevel == 1 ? "0" : headingLevel == 2 ? "80" : "40", After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto });
        AddInlineRuns(paragraph, text, style, new RunProperties(new FontSize { Val = fontSize.ToString() }, new Color { Val = color }, new Bold()));
        return paragraph;
    }

    private static Paragraph CreateListParagraph(string text, bool isNumbered, MarkdownToWordStyleOptions style)
    {
        var paragraph = CreateBodyParagraph(style);
        paragraph.ParagraphProperties!.Append(new Indentation { Left = style.ListIndentTwips.ToString() });
        string prefix = isNumbered ? "• " : "• ";
        paragraph.Append(new Run(new Text(prefix) { Space = SpaceProcessingModeValues.Preserve }));
        AddInlineRuns(paragraph, text, style);
        return paragraph;
    }

    private static Paragraph CreateCodeParagraph(string text, MarkdownToWordStyleOptions style)
    {
        var paragraph = new Paragraph();
        paragraph.Append(new Run(
            new RunProperties(
                new FontSize { Val = style.CodeFontSizeHalfPoints.ToString() },
                new RunFonts { Ascii = style.CodeFontName, HighAnsi = style.CodeFontName }),
            new Text(text) { Space = SpaceProcessingModeValues.Preserve }));
        return paragraph;
    }

    private static Paragraph CreateHorizontalRuleParagraph()
    {
        var paragraph = new Paragraph();
        paragraph.ParagraphProperties = new ParagraphProperties(
            new ParagraphBorders(
                new BottomBorder
                {
                    Val = BorderValues.Single,
                    Size = 8,
                    Space = 1
                }));
        paragraph.Append(new Run(new Text(string.Empty)));
        return paragraph;
    }

    private static Paragraph CreateParagraphWithInlineFormatting(string text, MarkdownToWordStyleOptions style)
    {
        var paragraph = CreateBodyParagraph(style);
        AddInlineRuns(paragraph, text, style);
        return paragraph;
    }

    private static Paragraph CreateBodyParagraph(MarkdownToWordStyleOptions style)
    {
        return new Paragraph(new ParagraphProperties(new SpacingBetweenLines { After = "0", Line = "240", LineRule = LineSpacingRuleValues.Auto }, new RunProperties(new RunFonts { Ascii = style.BodyFontName, HighAnsi = style.BodyFontName }, new FontSize { Val = style.BodyFontSizeHalfPoints.ToString() })));
    }

    private static void AddInlineRuns(Paragraph paragraph, string text, MarkdownToWordStyleOptions style, RunProperties? baseProperties = null, string? fontName = null)
    {
        string selectedFontName = fontName ?? style.BodyFontName;

        RunProperties GetRunProperties(params OpenXmlElement[] formatting)
        {
            var properties = new RunProperties(
                new RunFonts { Ascii = selectedFontName, HighAnsi = selectedFontName },
                new FontSize { Val = style.BodyFontSizeHalfPoints.ToString() });

            if (baseProperties is not null)
            {
                foreach (OpenXmlElement property in baseProperties.ChildElements)
                {
                    properties.Append(property.CloneNode(true));
                }
            }

            foreach (OpenXmlElement property in formatting)
            {
                properties.Append(property);
            }

            return properties;
        }

        int index = 0;
        while (index < text.Length)
        {
            if (TryMatchPrefix(text, index, "**", out int boldEnd))
            {
                string value = text[(index + 2)..boldEnd];
                paragraph.Append(new Run(
                    GetRunProperties(new Bold()),
                    new Text(value) { Space = SpaceProcessingModeValues.Preserve }));
                index = boldEnd + 2;
                continue;
            }

            if (TryMatchPrefix(text, index, "__", out boldEnd))
            {
                string value = text[(index + 2)..boldEnd];
                paragraph.Append(new Run(
                    GetRunProperties(new Bold(), new Underline { Val = UnderlineValues.Single }),
                    new Text(value) { Space = SpaceProcessingModeValues.Preserve }));
                index = boldEnd + 2;
                continue;
            }

            if (TryMatchPrefix(text, index, "*", out int italicEnd))
            {
                string value = text[(index + 1)..italicEnd];
                paragraph.Append(new Run(
                    GetRunProperties(new Italic()),
                    new Text(value) { Space = SpaceProcessingModeValues.Preserve }));
                index = italicEnd + 1;
                continue;
            }

            if (TryMatchPrefix(text, index, "{% raw %}`", out int codeEnd))
            {
                string value = text[(index + 1)..codeEnd];
                paragraph.Append(new Run(
                    GetRunProperties(new RunFonts { Ascii = style.CodeFontName, HighAnsi = style.CodeFontName }),
                    new Text(value) { Space = SpaceProcessingModeValues.Preserve }));
                index = codeEnd + 1;
                continue;
            }

            int nextToken = FindNextTokenIndex(text, index);
            string plainText = text[index..nextToken];
            paragraph.Append(new Run(GetRunProperties(), new Text(plainText) { Space = SpaceProcessingModeValues.Preserve }));
            index = nextToken;
        }
    }

    private static bool TryMatchPrefix(string text, int startIndex, string token, out int endIndex)
    {
        endIndex = -1;

        if (startIndex < 0 || startIndex >= text.Length)
        {
            return false;
        }

        if (!text.AsSpan(startIndex).StartsWith(token))
        {
            return false;
        }

        int searchIndex = startIndex + token.Length;
        if (searchIndex > text.Length)
        {
            return false;
        }

        endIndex = text.IndexOf(token, searchIndex, StringComparison.Ordinal);
        return endIndex > startIndex;
    }

    private static int FindNextTokenIndex(string text, int startIndex)
    {
        int bold = text.IndexOf("**", startIndex, StringComparison.Ordinal);
        int underline = text.IndexOf("__", startIndex, StringComparison.Ordinal);
        int italic = text.IndexOf('*', startIndex);
        int code = text.IndexOf('`{% endraw %}', startIndex);

        int next = text.Length;
        if (bold >= 0) next = Math.Min(next, bold);
        if (underline >= 0) next = Math.Min(next, underline);
        if (italic >= 0) next = Math.Min(next, italic);
        if (code >= 0) next = Math.Min(next, code);

        return next;
    }

    private static string ResolveProjectRoot()
    {
        DirectoryInfo? dir = new(AppContext.BaseDirectory);

        while (dir is not null)
        {
            if (dir.EnumerateFiles("*.csproj", SearchOption.TopDirectoryOnly).Any())
            {
                return dir.FullName;
            }

            dir = dir.Parent;
        }

        return Directory.GetCurrentDirectory();
    }
}

{% raw %}

Love C# & AI!

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!

DEV Community: David Au Yeung

Python has a tool for that. What about .NET?

Start with the problem, not the package

A little .NET toolbox

Not Python versus .NET

Inspiration and credit

I Love .NET Blazor. Now It Can Build Agentic UI, Not Just Chat Boxes

Introduction

What Is Agentic UI?

What We Are Building

A Preview Warning Before We Start

Step 1: Install .NET 11

Step 2: Add the AI Building Blocks

Step 3: Configure Ollama

Step 4: Start With ChatPage and UIAgent

Sharing the Conversation With a Toolbar

How a Message Reaches Ollama

Step 5: Turn a Tool Result Into a Typed Card

Register the Tool

Map the Result to a Block

Render the Card

Step 6: Let a Tool Change the Blazor UI

Step 7: Ask the Human Before an Important Action

Step 8: Share State With the Agent

Step 9: Preview a Document Change Before Saving It

Step 10: Show a Live Plan and Real Tool Activity

What About Reasoning Summaries?

Step 11: Run the Demo

Limitations and Next Steps

Final Thoughts

References

Do you have "Monthly Limit Anxiety" like me?

I Stopped Asking Copilot to Format My 100-Page Markdown Reports. Here Is the Deterministic C# Fix

Introduction

What We Are Building

The Demo File: Markdown/Example.txt

Prerequisites

Step 1: Define the Conversion Options

Step 2: Keep the Style in One Place

Step 3: Use an Existing Document as the Formatting Reference

Step 4: Convert the Markdown File

Step 5: What the Parser Converts

Step 6: Run It

A Word About Tables

Why This Saves More Than Tokens

A Practical Workflow for Long AI Research Results

Limitations and Next Steps

Final Thoughts

Complete MarkdownToWordService Source

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

Step 4: Start With `ChatPage` and `UIAgent`

The Demo File: `Markdown/Example.txt`

Complete `MarkdownToWordService` Source

`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/*`)