DEV Community: Shahriar Haque Abir

Building a custom profile in PowerShell

Shahriar Haque Abir — Tue, 25 Aug 2026 12:43:35 +0000

How I built PowershellOps, a terminal dashboard with 126 functions, 90 one-word commands, and a llama.cpp-powered AI hub that never touches the cloud. Full walkthrough, real code, and the forks in the road where you should disagree with me.

Every Windows machine ships with a diagnostics API that most developers never open. CIM classes report your CPU model, battery wear, thermal zones, Defender status, DNS cache, and signed-driver faults, all locally, all queryable from a shell you already have. Pair that with a small language model running on your own GPU and you get something no SaaS dashboard sells: an operations copilot that answers "why is my fan loud" without uploading a byte.

This post walks the whole build, zero to shipped product. By the end you will have a PowerShell profile where typing dash renders an 11-suite command center, fix pipes your last error to a local model for diagnosis, mem saves notes with automatic secret redaction, and 90 short verbs like temps, shield, and dnsbench resolve from anywhere in your shell. The finished project lives at github.com/shahriarhaqueabir/PowershellOps (v12.0.0, MIT licensed), so you can compare every step against the real source.

Some steps I hand you completely. Others I leave half-open on purpose, marked Your turn, because you learn the CIM layer by writing your own queries, not by pasting mine. And at each architectural fork I lay out the alternatives, including the ones I rejected and why.

What We Are Building

The product has four layers:

A sensor layer. Plain functions that query CIM/WMI and return formatted output: hardware specs, uptime, RAM sticks, battery health, temperatures, fans, displays, network adapters, SMB shares, certificate stores.
An alias surface. Every sensor gets a one-word name. raminfo, patchhistory, drivehealth. Ninety of them, all backed by a single ordered hashtable that doubles as the dashboard's data source.
An AI hub. A local llama.cpp server speaking the OpenAI-compatible protocol on 127.0.0.1:8081. Functions pipe data into it: Get-Process | ai "what's using the most memory?".
A delivery layer. A staged installer that works from stock Windows PowerShell 5.1, a hardened profile template, and a 27-test suite that runs hermetically in CI-style isolation.

Why is this useful when Get-ComputerInfo exists? Because raw cmdlets answer questions one at a time. A copilot answers the questions you ask at 9am: is anything hot, is anything patched, did my disk start filling up, and what was that registry tweak I saved last month. Speed matters too. Each sensor is one CIM query, so stat returns a full system pulse in about a second.

There is also the privacy argument, which turned out to matter more than I expected. The moment you route system telemetry through a cloud API, you need a data policy. Route it through localhost and the policy is trivial: nothing leaves the machine. My memory store holds API keys and hostnames, and I sleep fine because every write passes a redaction filter first.

Fork Number One: Which Inference Engine

Before any code, pick how the model runs. The candidates:

Option	Strengths	Weaknesses
llama.cpp server	Single exe, OpenAI-compatible HTTP endpoint, GGUF models, full control over flags	You manage download, port, lifecycle
Ollama	One-command install, model management built in	Daemon owns the port; harder to pin versions; another product to trust
LM Studio	Nice GUI for model shopping	GUI-first, weaker headless story
Cloud API	Zero setup, best models	Per-token billing, telemetry leaves the box, breaks offline

I chose llama.cpp for three reasons. First, scriptability: the server is one process I start and stop from PowerShell, so the module can auto-start it on demand. Second, the OpenAI-compatible /v1/chat/completions endpoint means my client code would survive a future engine swap unchanged. Third, reproducibility: the installer pins the engine version in vars.ps1 and downloads the exact binary it expects.

If you run Ollama already, keep it. The client function in step 5 targets an HTTP contract, not a vendor. Point $script:HawkLlamaUri at Ollama's OpenAI shim and everything downstream works.

Your turn: decide your engine before writing client code, and write down its URI and health-check endpoint. That decision document will save you an hour later.

Step 1: A Module Skeleton That Scales

Skip the single-file monolith. It feels faster and costs you later, because PowerShell modules load their .psm1 once and every edit during development means a full reload cycle. Instead, split concerns into numbered files and let the loader dot-source them in filename order:

# HawkwardHybrid.psm1
foreach ($domainFile in Get-ChildItem -LiteralPath $PSScriptRoot -Filter '*.ps1' | Sort-Object Name) {
    . $domainFile.FullName
}

Export-ModuleMember -Function @('Get-HawkConfig', 'Invoke-HawkAI', ...)
Export-ModuleMember -Alias @('ai', 'fix', 'dash', ...)

The numeric prefixes (00-Core.ps1, 20-AI.ps1, 80-LegacyMatrix.ps1) enforce load order: core helpers before features that call them. One manifest, one version, one export surface.

Now the low-level detail that bites everyone: PowerShell exports are a contract between three places, and they drift independently. The manifest's FunctionsToExport controls what Import-Module exposes. The .psm1's Export-ModuleMember controls the live session. And any alias map you keep in a separate file is a third list that can rot. During this project's final review wave, the manifest listed 90 aliases while the loader exported 57. Every direct Import-Module consumer saw phantom commands. The fix became a permanent test: assert set equality between all three lists on every run, never a threshold like "at least 80".

$m = Get-Module HawkwardHybrid
$manifest = Import-PowerShellDataFile .\HawkwardHybrid.psd1
@($manifest.AliasesToExport | Where-Object { $_ -notin $m.ExportedAliases.Keys }) | Should -BeNullOrEmpty

Your turn: create the folder, write a Get-HelloOps function, wire the manifest, and prove the import path works before adding anything else. If you skip this and the parity test, you will meet the drift bug eventually, on a worse day.

Step 2: The Sensor Layer, or Talking to Your Motherboard

CIM is the workhorse. Each sensor is a query plus formatting. Two examples show the whole pattern:

function Get-HawkRamInfo {
    Get-CimInstance Win32_PhysicalMemory |
        Select-Object BankLabel, Capacity, Speed, Manufacturer |
        Format-Table -AutoSize
}

function Get-HawkThermals {
    $zones = @(Get-CimInstance -Namespace root/wmi -ClassName MSAcpi_ThermalZoneTemperature `
               -ErrorAction SilentlyContinue)
    if (-not $zones) {
        Write-Host "No ACPI thermal zones exposed by this hardware/driver stack." -ForegroundColor DarkGray
        return
    }
    $zones | ForEach-Object {
        $celsius = [Math]::Round(($_.CurrentTemperature / 10.0) - 273.15, 1)
        $state = if ($celsius -ge 85) { 'CRITICAL' } elseif ($celsius -ge 70) { 'HOT' }
                 elseif ($celsius -ge 50) { 'WARM' } else { 'NOMINAL' }
        [PSCustomObject]@{ Zone = $_.InstanceName; TemperatureC = "$celsius C"; State = $state }
    } | Format-Table -AutoSize
}

Three things worth noticing in the thermal function, because each is a small lesson:

The Kelvin conversion. ACPI reports temperature in tenths of a degree Kelvin. Divide by 10, subtract 273.15. If your readings come back around 3000, you forgot the scale, and yes, that is exactly what the raw number looks like the first time.

Graceful degradation. Many consumer boards expose no thermal zones without vendor drivers, and Win32_Fan often returns nothing because fan curves live in the embedded controller, outside WMI's reach. Return a friendly dark-gray hint instead of an error. A diagnostics tool that errors on normal hardware states trains users to ignore it.

Objects, then format. Emit [PSCustomObject] and pipe through Format-Table at the end. Anyone can then do temps | Where-Object State -eq 'HOT' themselves. Format early and you've thrown away the data.

The fork here: Get-CimInstance versus Get-WmiObject. The latter is deprecated and absent from PowerShell 7, so the choice is made for you. But within CIM there are still decisions. Some data lives in the default root/cimv2 namespace, thermals hide in root/wmi, disk health sits in root\Microsoft\Windows\Storage with class MSFT_PhysicalDisk. I query the storage namespace directly rather than calling Get-PhysicalDisk, which keeps behavior identical across Windows builds.

Your turn: write battery health yourself. Query Win32_Battery, compute FullChargeCapacity / DesignCapacity * 100, round to one decimal, and handle the desktop case where the query returns nothing. Then try Win32_Processor, Win32_VideoController, and Get-HotFix on your own machine. Ten functions in, you'll stop needing my snippets.

Step 3: Ninety Aliases Without Losing Your Mind

Short names are the product. Nobody types Get-HawkScheduledTaskRiskAudit; they type taskaudit. But ninety Set-Alias calls scattered across files become unmaintainable, so the entire alias surface lives in one ordered hashtable:

$script:HawkAliasMap = [ordered]@{
    ai        = 'Invoke-HawkAI'
    dash      = 'Show-HawkDashboard'
    temps     = 'Get-HawkThermals'
    shield    = 'Get-HawkShield'
    # ... 86 more
}

Registration happens twice, by design. Once in module scope at dot-source time, so Export-ModuleMember -Alias publishes a truthful surface to anyone who imports the module. Once in global scope via Set-HawkAliases at profile load, so interactive sessions get the shortcuts even without an explicit import. Same map, both scopes, one source of truth.

function Set-HawkAliases {
    foreach ($name in $script:HawkAliasMap.Keys) {
        Set-Alias -Scope Global -Name $name -Value $script:HawkAliasMap[$name] -Force
    }
}

The honest objection: aliases die at the process boundary. Call temps from a script or another tool and PowerShell resolves it only if the profile loaded. Native executables survive everywhere. If your audience lives in cmd.exe and scheduled tasks, consider shipping a thin compiled CLI instead, or generating .cmd shims. I stayed with aliases because the target user is me, inside PowerShell, dozens of times a day, and the dashboard-to-command guarantee (every tile renders a name that resolves) only needs in-shell truth.

That guarantee is testable, by the way, and worth testing. Extract tile aliases from the dashboard source with a regex, diff them against the alias map, fail the suite on either direction of mismatch. This exact test caught dead tiles after I renamed functions without updating the menu.

Your turn: add three sensors of your own from step 2, give each an alias, and extend the parity test to cover them. Notice how the map format makes the dashboard update free: the menu iterates the same structure.

Step 4: A Dashboard Worth Staring At

dash prints eleven suites, each a titled grid of emoji-tiled commands. The implementation is an ordered dictionary of suites, each holding a title, an icon, and rows of (glyph, label, alias) triples, rendered by one loop. No TUI framework, no ncurses clone. Write-Host with colors covers it.

Two low-level notes from the trenches:

UTF-16 surrogate pairs. Emojis above the Basic Multilingual Plane (the robot 🤖 is U+1F916) encode as two UTF-16 code units. If you probe render output character-by-character, remember [char]0xD83E followed by [char]0xDD16 forms the glyph, and piping chars through some stringifications mangles them into decimal digits. Test with .Contains($pair) on the joined pair.

Console encoding. Wrap [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new() in try/catch. On some hosts the setter throws, and a crash inside your profile renderer poisons every session.

Your turn: design your own suite row before looking at mine. Decide first what belongs on a glanceable menu and what deserves omission. Curation is the actual product skill here; rendering is twenty lines.

Step 5: Wiring the Local Model

The AI hub starts with a server manager: download the pinned llama.cpp build (the installer handles this in steps/01-engine.ps1 and 02-model.ps1), place a GGUF model under ~\Models\GGUF, then start llama-server.exe with a port and context flags. Health check via TCP probe with a retry loop, because the server accepts TCP connections a moment before it can serve.

The client function carries the design weight. Its signature tells the story:

function Invoke-HawkAI {
    [CmdletBinding()]
    param(
        [Parameter(ValueFromPipeline = $true)] $InputData,
        [Parameter(Position = 0)][string]$Instruction,
        [string]$Model = $script:HawkLlamaModelPath,
        [int]$TimeoutSec = 300,
        [switch]$RedactSensitive,
        [switch]$PassThru
    )
    # buffer pipeline input, stringify, redact, POST to /v1/chat/completions, stream reply
}

Pipeline support is what makes it feel native. Get-EventLog System -Newest 50 | ai "summarize failures" buffers objects through the process block, stringifies with Out-String, and sends the bundle as evidence alongside your instruction. Streaming keeps perceived latency low; a 4B-parameter model on a modest GPU starts answering in about a second.

Redaction runs before the payload leaves the process, always available, opt-in per call:

[regex]::Replace($text,
    '(?im)^(\s*[^=\r\n]*(?:secret|token|password|api.?key|private.?key)[^=\r\n]*\s*=\s*).+$',
    '$1<REDACTED>')

plus a second pass for the JSON "key": "value" shape. Regex redaction is beatable, and I say so in the docs. Structured secrets in weird formats can slip. But the common cases, dotenv lines and JSON config blobs, get caught, and the defense costs zero dependencies.

Small local models bend prompt constraints, so expect to iterate on wording. Mine instructs the model to answer from provided data first, preserve units, stay concise, and suggest the smallest next check when unsure. Prompt engineering for 4B-class models is constraint engineering.

Fork number two: model choice. Bigger is better until your RAM disagrees. A Q4-quantized 4B model runs in under 4 GB and answers fast; an 8B wants about 6 GB and reasons better; anything above 14B turns your copilot into a slideshow unless you own real VRAM. I ship with Qwen3-family GGUFs via the Unsloth quants, and the installer lets you pick. Benchmark on your machine: time ten stat | ai calls at each size and let the numbers choose.

Your turn: implement the retry logic. On connection refused, wait two seconds, re-probe, auto-start the server if configured, and cap total attempts. My first version raced the server startup and failed at random, which is why Start-HawkLlamaServer now polls instead of sleeping on a fixed timer.

Step 6: Verbs That Do Something

Raw AI chat is table stakes; the value shows in composed verbs. fix is the best example, and it is twelve lines:

function Invoke-HawkShortFix {
    param([string]$Context)

    $err = $global:Error | Select-Object -First 1
    if (-not $err) {
        Write-Host 'No error found in $Error to remediate.' -ForegroundColor Yellow
        return
    }

    $payload = "Last PowerShell error:`n$($err.ToString())`n`nInvocation context:`n$($err.InvocationInfo.PositionMessage)"
    if ($Context) { $payload += "`n`nExtra context:`n$Context" }

    $payload | Invoke-HawkAI -Instruction 'Diagnose this PowerShell error and give a concrete fix (commands where possible). Be concise.' -RedactSensitive
}

$Error[0] plus InvocationInfo.PositionMessage gives the model the exception text and the exact line where it threw. That pairing fixes most errors in one shot because the model sees what you saw.

On top of these sit router functions with ValidateSet parameters: hub fix, hub stat, sysdiag temp, auditdiag defender. A dispatcher is a switch statement over validated types, each case delegating to the underlying function. ValidateSet buys tab-completion and rejects typos before your switch ever runs.

Your turn: add an explain verb that takes a command name, pulls its help with Get-Help -Full, and asks the model to produce a plain-language explanation with two examples. You will need exactly one new concept beyond what this post covered.

Step 7: Memory That Redacts Itself

The memory system stores notes as JSON Lines, one entry per line, at Documents\PowerShell\Memory\hawk-memory.jsonl. Entries carry an id, typed tags (note/preference/fact/incident/command/link), a confidence score, a pinned flag, and the text. Search scores each term: plus two per term matching the text, plus one matching a tag, flat plus-two bonus for pinned entries, drop zeros, sort descending:

foreach ($t in $terms) {
    if ($e.Text -match [regex]::Escape($t))       { $score += 2 }
    if (($e.Tags -join ' ') -match [regex]::Escape($t)) { $score += 1 }
}
if ($e.Pinned) { $score += 2 }

The fork everyone argues: why not embeddings? Vector search would find "that quantization thing" when you search "model compression formats", which term matching misses. My counterargument: this store holds hundreds of entries, not millions. Term scoring with tags covers recall at this scale, adds zero dependencies, stays human-readable when you open the file, and never needs an embedding model loaded. When the store crosses a few thousand entries, revisit. Ship the boring version first and write down the migration trigger. SQLite would also work and gives you real indexes; JSONL won because the whole database fits in one Get-Content call and survives any editor.

Every write funnels through the same redaction filter as AI payloads, so mem api_key=sk-whatever stores <REDACTED>. Test this in the suite: save a fake key, read the file, assert the secret is gone. That test has earned its keep.

Your turn: implement rotation. When the file passes N entries, archive the oldest unpinned third to a dated sidecar file. Decide what N should be and defend it in a comment.

Step 8: The Installer Problem Nobody Escapes

Shipping a PowerShell product to other machines means answering an awkward question: which PowerShell? Windows still boots with 5.1, while serious modules want 7. My answer is a staged bootstrap: install.ps1 runs on whatever shell invoked it, checks for pwsh, installs it via winget if missing, then re-executes itself under 7 with the original arguments forwarded.

After the handoff, numbered steps run in order: fetch the pinned engine, fetch the model, copy the module into the user's Documents\PowerShell\Modules, write config JSON, install the hardened profile template, register an update check. Each step logs to a file and exits nonzero on failure, so automation can detect partial installs.

The profile template deserves its own sentence: wrap every initialization phase in try/catch. A profile that throws strands users in a broken shell, and since agents wrote much of this code, defensive loading is non-negotiable.

Step 9: Tests That Keep Everyone Honest

Twenty-seven tests run in seconds, and they share one property: they touch nothing outside a staging directory. The suite redirects the PowerShell profile root to a temp location (Set-HawkStagingRoot), isolates config via HAWK_CONFIG_PATH, and treats any network touch as a defect. Early versions could hit real downloads mid-test; the fence went up, and now any run that touches the network fails.

Beyond unit checks, the valuable tests are contracts:

Parity: psd1 exports equal psm1 exports equal alias-map keys, set equality both directions.
Surface: every dashboard tile resolves to a registered alias; every alias appears in the manual's index; counts match the header claims.
Smoke: stage the real profile template, load it in a fresh process, assert dash, specs, and ai resolve with zero errors.
Docs: the manual mentions only exported functions; phantom references fail the build. (This test exists because earlier docs referenced commands I had retired. Docs lie without getting caught; tests make lying expensive.)

When you build with AI assistance, as I did, this suite is the difference between delegation and hope. Agents generate plausible code without hesitation. Set-equality gates catch the drift that confidence hides. My final review wave found 17 issues across ten reviewer passes; one round fixed eight of them because the verification commands existed and ran green afterward.

Your turn: take whatever you built in steps 1 through 7 and write the parity test first, before the next feature. Then break something on purpose (rename a function without updating the manifest) and watch the right test fail with the right message.

Step 10: Ship It

Documentation earns its push. Two artifacts mattered most: a README whose alias index is generated-checked against the manifest (all 90 present, zero phantoms), and a manual mapping every command to its underlying cmdlets and CIM classes. Writing the sensor map exposed three stale references and two phantom aliases in my own docs, which is the point: the audit is for you.

GitHub-specific lessons, learned the hard way:

Anchor links break when headings contain decorative characters. GitHub's slugger keeps trailing hyphens from ── SECTION ── styles, so #features 404s while #-features- resolves. Strip decorations from headings or compute slugs exactly.
Tag the release: git tag -a v12.0.0 -m "..." then git push origin v12.0.0. Draft the Release page from the tag and paste real release notes; changelogs written from memory lie.
Fill the About description and topics. Searchable repos get contributors; invisible ones get neither.
If you publish to PSGallery, know that the legacy Publish-Module shells out to dotnet pack and demands a .NET SDK. The modern Publish-PSResource packs in-process and skips that requirement. I skipped gallery publishing altogether; GitHub plus the installer covers my distribution needs.

Where You Take It Next

The natural extensions, about in order of payoff: scheduled hawkdaily runs writing timestamped reports to disk; WMI event subscriptions pushing alerts instead of polling; more dispatch verbs as your sensor collection grows; swapping the term-scoring memory for embeddings when it earns the complexity. Fork the repo, keep what you use, delete the rest. Ninety aliases is a menu, and menus invite substitution.

If you want the companion piece, the repository also documents how this whole product was built with an AI coding agent: phase maps, prompt patterns, the review loop, and a museum of failures that became guardrails (docs/AGENTIC-IDE-TUTORIAL.md).

Build your own suite. Break my defaults. The whole point of a local copilot is that it answers to you.

Building an AI-Augmented Web Portfolio with Qwen, WebLLM and WebGPU

Shahriar Haque Abir — Sun, 09 Aug 2026 23:00:16 +0000

Building an AI-Augmented Web Portfolio with Qwen, WebLLM and WebGPU

Build an AI-augmented web portfolio with Next.js 16.2.12, React 19, Tailwind CSS v4, WebLLM, WebGPU, and Qwen2.5–1.5B-Instruct running locally in the browser.

Most portfolios are built to be browsed. You open the homepage, read the About section, look through a few projects, maybe download a résumé, scroll and leave.

I wanted to change how visitors interact with a web portfolio. Not by putting a chatbot in the corner of the screen, but by making the AI part of the portfolio itself.

So I built an AI-Augmented Web Portfolio.

The website is still more or less a normal web application. There are pages, projects, experience, skills, navigation and all the things you'd expect from a typical portfolio. The difference is that there is another layer sitting on top of all that. A local AI system that can understand questions, find relevant information, navigate the portfolio and have a conversation with the visitor.

Before we dive into this, let's take a moment to align ourselves with the way of thinking. We are not just throwing everything at the LLM. No, if someone says "show me your projects", I don't need an LLM to figure out what that means. Or if someone asks for a basic fact about my experience, I don't need an LLM for that either. The application handles those things itself. The model is there when a more contextual answer is useful. That became the basic idea behind the architecture:

Don't make the AI the application. Make the AI another component of the application.

The Tech Stack

Framework: Next.js 16.2.12 (App Router, Static Generation)
Language: TypeScript 5.8
UI Library: React 19.2 (Canary)
AI Runtime: WebLLM (MLC-AI)
AI Model: Qwen2.5–1.5B-Instruct-q4f16_1-MLC (4-bit quantized)
Inference: WebGPU
Styling: Tailwind CSS v4 (CSS-first config)
Animation: Motion v12 (formerly Framer Motion)
Voice: Web Speech API (STT) + ElevenLabs (TTS via Proxy)
Deployment: Vercel
Testing: Playwright

You can use your own stack and I am sure there are plenty of alternatives out there but for me at the moment of developing this project, this stack was the best option available to my knowledge. The important part isn't any individual library. It's where the pieces run.

The portfolio UI, routing logic, fallback engine and LLM inference run on the client. While the voice output is the exception: ElevenLabs is accessed through a small server-side proxy so the API key doesn't have to be exposed in the browser. The voice input and output is an additional accessibility feature and can be excluded if a truly serverless development is desired.

The Architecture: A Cooperative Brain

The first version of the idea was simple:

Visitor
   ↓
LLM
   ↓
Answer

That worked, but it created a problem.

The model takes time to initialize. The browser has to load the model shards, and WebGPU has to initialize. Furthermore, there are plenty of situations where using an LLM is simply unnecessary.

So the next question was "What can the application do when the model isn't available and when does the LLM step in?"

Instead of making every interaction go through the model, the portfolio became a cooperative parallel handoff system across several tiers of intelligence.

The application doesn't sit around waiting for the LLM to become ready. It does what it can immediately. When the model is available, it can take the interaction further.

1. Offloading Reasoning to a WebWorker

Running an LLM in the browser is not exactly lightweight. There is model initialization, WebGPU setup, token generation, and streaming to deal with.

I didn't want that work competing with the UI thread. So WebLLM runs inside a Web Worker.

The worker owns the model instance and communicates with the main application through messages. Accessing WebGPU inside a Worker is the secret sauce, as it offloads the heavy GPGPU work from the main thread entirely.

A simplified version looks like this:

// src/lib/worker.ts
const MODEL_ID = "Qwen2.5-1.5B-Instruct-q4f16_1-MLC";

class WebLLMEngineSingleton {
  static instance: MLCEngine | null = null;
  static async getInstance() {
    if (this.instance === null) {
      this.instance = await CreateMLCEngine(MODEL_ID, {
        initProgressCallback: (report) => {
          self.postMessage({
            status: "progress",
            data: {
              progress: Math.round((report.progress ?? 0) * 100),
            },
          });
        },
      });
    }
    return this.instance;
  }
}

The singleton isn't there because singletons are fashionable. It's there because I only want one model engine managing the local inference session.

If React causes the surrounding application to re-render, I don't want another initialization path accidentally creating another engine — triggering parallel ~950MB redownloads of the model weight shards and ballooning the ~1.6GB VRAM active execution footprint which is already quite heavy.

The worker then sends progress and generated text back to the main thread:

worker.onmessage = (event) => {
  if (event.data.status === "progress") {
    setProgress(event.data.data.progress);
  }
  if (event.data.status === "stream") {
    setMessages((prev) =>
      updateLastMessage(prev, event.data.text)
    );
  }
};

The application consumes the results. The UI doesn't have to directly manage the model.

2. Don't Ask an LLM to Do Something a Router Can Do (Tier 1)

One of the simplest things the assistant can do is navigate the portfolio.

If someone says: "Show me the projects." I don't need Qwen to reason about that.

A small command router can handle it instantly. The router scores known keywords against the available views and returns the strongest match.

// src/hooks/useCommandRouter.ts
function detectView(input: string) {
  const text = input.toLowerCase().trim();
  const scores = new Map<ViewKey, number>();
  for (const [view, data] of Object.entries(viewMap)) {
    const keywordScore = data.keywords.reduce(
      (total, kw) =>
        total + (text.includes(kw) ? data.weight : 0),
      0
    );
    scores.set(view, keywordScore);
  }
  const [bestView, bestScore] = [
    ...scores.entries(),
  ].sort((a, b) => b[1] - a[1])[0];
  return bestScore > 0
    ? { view: bestView, score: bestScore }
    : { view: null, score: 0 };
}

It's deliberately boring. And that's the point. This prevents the model from inventing a navigation decision when the application already knows the answer.

3. The Fallback Engine (Tier 2)

Navigation isn't the only thing that can bypass the model. There are plenty of questions where the portfolio already has the information:

Who is Shahriar?
What technologies does he use?
What is his experience?

For these, there is a lightweight intent engine that evaluates queries in <5ms.

// src/lib/fallback-engine.ts
const intentPatterns = [
  {
    name: "who_is",
    keywords: ["shahriar", "bio", "background"],
    weight: 3,
    answer: answerAboutBio,
  },
  {
    name: "skills",
    keywords: ["tools", "tech stack", "languages"],
    weight: 2,
    answer: answerSkillsTools,
  },
];

export function buildFallbackAnswer(userText: string) {
  const lower = userText.toLowerCase();
  const hit = intentPatterns.find(
    (p) => scoreIntent(lower, p) > 0.3
  );
  return hit ? hit.answer(userText) : null;
}

This gives the application something useful to say even if the LLM isn't ready. The portfolio shouldn't feel broken during the several seconds the model takes to initialize.

4. Then Let the Model Take Over (Tier 3)

Once the local model is ready, questions that don't fit the deterministic paths can be passed to Qwen.

Instead of just matching: "What are your skills?" the model can deal with something more open-ended:

"I'm looking for someone with experience working across support, networking and AI tooling. What have you actually built that would be relevant?"

That's a much better use for an LLM.

The application already has the portfolio data. The model's job is to turn that information into a useful response for the visitor.

Known problem
    ↓
Deterministic solution

Unknown / contextual problem
    ↓
Local LLM

That's a much better division of labour.

5. Letting the Model Control the Interface

I didn't just want the model to talk about the portfolio. I wanted it to be able to interact with the portfolio.

If a visitor asks to see my projects, or asks a question where navigating to the projects section would be helpful, the model can emit a control directive such as:

INITIATING_NAVIGATION: projects

The application detects that directive and performs the navigation itself. The model doesn't directly manipulate the React application.

Because LLMs stream token-by-token, a tag might split across two chunks. We store the accumulated stream and check the full text rather than assuming a control directive will arrive in one chunk:

// src/hooks/usePortfolioWorker.ts
const visibleText = rawText
  .split("\n")
  .filter((line) => !line.startsWith("INITIATING_"))
  .join("\n");
if (rawText.includes("INITIATING_NAVIGATION:")) {
  const view = rawText
    .split("INITIATING_NAVIGATION:")[1]
    .trim()
    .toLowerCase();
  if (VALID_VIEWS.includes(view)) {
    onNavigate(view);
  }
}

The idea is simple: The model proposes. The application validates. Following this idea keeps the LLM inside a controlled boundary.

6. The TTS and STT voice problem.

The AI itself is local, but voice is different.

We can also enable speech input for the portfolio by using the browser's Web Speech API. For speech output, I used ElevenLabs free tier.

The TTS request goes through a stateless Next.js API route:

Browser
   │
   │ text
   ▼
Next.js API route
   │
   │ API key stays here
   ▼
ElevenLabs
   │
   │ audio
   ▼
Browser

The API route protects our API keys and gives me somewhere to apply basic request controls. Requests are capped at 500 characters to protect quotas, and there is an ephemeral in-memory IP-based rate limit within the serverless module scope to prevent basic cost spikes.

// src/app/api/tts/route.ts
const RATE_LIMIT_MAP = new Map<string, { count: number; reset: number }>();

It isn't pretending to be a production abuse-prevention system, but it's enough for this project. I hope…

7. The UI Shouldn't Have to Wait for AI

This is probably the most important lesson from the project.

A common pattern with AI interfaces is:

User
 ↓
Loading...
 ↓
AI
 ↓
Response

I wanted something closer to:

User
 ↓
Application responds immediately
 ↓
Local model becomes available
 ↓
AI adds more context

If WebGPU isn't available, the deterministic parts can still work. If a question has an obvious answer, the application doesn't need to wake up a language model.

8. Testing the Handoff

This kind of interface is slightly harder to test than a normal website.

User asks question
        ↓
Fallback answer appears
        ↓
Local model becomes available
        ↓
Model response streams
        ↓
Control directive detected
        ↓
Navigation occurs

I used Playwright to test these interaction paths and make sure the handoff doesn't leave the interface in an awkward state.

The Trade-Off

Instead of my server paying for every inference request, the visitor's machine does the work. That comes with some obvious trade-offs:

The model has to be downloaded.
WebGPU support matters.
Device memory and GPU capability matter.
Performance is dependent on user's machine.
Voice still relies on external services.

Conclusion

The goal was to reimagine a website where the visitor feels less like browsing a collection of pages and more like interacting with the persona behind it.

That's ultimately what I wanted from the project.

Try it

Live Demo: https://shahriarhaqueabirportfolio.vercel.app

Source: https://github.com/shahriarhaqueabir/ShahriarHaqueAbirPortfolio