[{"_1":2,"_161":-5,"_162":-5},"loaderData",{"_3":4},"root",{"_5":6,"_34":35},"blog",{"_7":8,"_27":28},"metas",[9],{"_10":11,"_12":13,"_14":15,"_16":17,"_18":19,"_24":25,"_26":-7},"slug","local-ai-on-a-16gb-macbook-air","title","Running Local AI on a 16GB MacBook Air","date","2026-10-05","excerpt","I tried a handful of small models with llama.cpp on a base M4 MacBook Air to see what local AI looks like on normal consumer hardware.","tags",[20,21,22,23],"local-ai","llama.cpp","macbook","llm","author","Chris Kwok","image","bySlug",{"_11":29},{"_10":11,"_12":13,"_14":15,"_16":17,"_18":19,"_24":25,"_26":-7,"_30":31,"_32":33},"content","# Running Local AI on a 16GB MacBook Air\n\nMy laptop is an M4 MacBook Air with 16GB of unified memory. For local AI that is not much. Most of the setups you see online have 64GB or more, or a desktop with a big GPU. But 16GB is what a normal person actually buys, so I wanted to know what local hosting looks like on this kind of machine, not on a workstation.\n\nShort version: a 9B model is smart enough but too slow, and a small MoE model turned out to be the sweet spot.\n\n## The setup\n\nI used llama.cpp on macOS. `llama-server` pulls a GGUF straight from Hugging Face and serves it on a local port, so trying a new model is one command.\n\nThis is the command for the 9B model I ended up preferring:\n\n```bash\nllama-server -hf ornith-ai/Ornith-1.5-9B-GGUF:Q4_K_M \\\n -ngl 99 -np 2 -c 49152 -fa on --temp 0.6 \\\n --cache-type-k q8_0 --cache-type-v q8_0 --no-mmproj \\\n --host 127.0.0.1 --port 8080 --jinja\n```\n\nMost of these flags are there because of the 16GB limit.\n\n- `-ngl 99` puts every layer on the GPU\n- `-c` is the context size, and it is the number I kept fighting with\n- `-np` is the number of parallel slots\n- `-fa on` turns on flash attention\n- `--cache-type-k q8_0 --cache-type-v q8_0` quantizes the KV cache, which saves memory so more context fits\n- `--no-mmproj` skips the vision part, because I only need text\n- `--jinja` uses the model's own chat template, which tool calling needs\n\nEverything is a Q4_K_M quant. On 16GB there is no room for anything bigger at this model size.\n\n## The 9B models\n\nI tried four of them. They are all the same size, so the commands are almost identical.\n\n- **Qwen 3.5 9B** (`unsloth/Qwen3.5-9B-GGUF`). The base model, and my baseline.\n- **OmniCoder 9B** (`Tesslate/OmniCoder-9B-GGUF`). An agent fine-tune.\n- **Ornith 1.5 9B** (`ornith-ai/Ornith-1.5-9B-GGUF`). Another agent fine-tune, and the one I prefer.\n- **Qwen 3.5 9B Uncensored** (`HauhauCS/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive`). An uncensored fine-tune. I ran this one at `--temp 0.9`, the rest at 0.6.\n\nOrnith is pretty good. It calls tools accurately and it is smart. If I only cared about the quality of the answers, I would stop here.\n\n1.5 is the newer release of Ornith. It is the same size as 1.0, so it needs the same memory, and its [model card](https://huggingface.co/ornith-ai/Ornith-1.5-9B-GGUF) reports small gains over 1.0 across the board: 70.6 against 69.4 on SWE-bench Verified, and 46.2 against 43.1 on Terminal-Bench 2.1.\n\nThe problem is speed. A 9B model on this laptop runs at about 8 tokens per second, and it drops to around 6 when the context fills up. That is fine for one question. It is painful for anything agentic, where the model reads tool output, thinks, calls another tool, and does that ten times in a row.\n\nThe other problem is context. A 9B model already takes a big part of the 16GB, so there is not much left. I ran most of them at 32k, and pushed Ornith to 49k. That sounds like a lot until an agent starts reading files.\n\n## The tiny one that was not useful\n\nI also tried going the other way with LFM 2.5 2.6B.\n\n```bash\nllama-server -hf LiquidAI/LFM2.5-2.6B-GGUF:BF16 \\\n -ngl 99 -c 131072 -np 3 -fa on \\\n --temp 0.1 --top-k 50 --repeat-penalty 1.1 \\\n --host 127.0.0.1 --port 8080\n```\n\nIt is small enough that I could run it unquantized with a 131k context and three slots. But it was not useful for what I wanted. Having a lot of context does not help when the model cannot do much with it.\n\n## Ling 3.0 Tiny\n\nThen I found Ling 3.0 Tiny. It is a lightweight hybrid reasoning MoE model with 7.9B total parameters, but only 1.3B of them are activated per token.\n\nThat one detail changes everything on this hardware. The model has the knowledge of a roughly 8B model, but each token only costs about as much compute as a 1.3B model. With a Q4 quant it runs at around 40 tokens per second on my Air, and it can fit a lot of context.\n\n```bash\nllama-server -hf inclusionAI/Ling-3.0-tiny-GGUF:Q4_K_M \\\n -ngl 99 -c 65536 -np 1 -fa on --temp 0.6 \\\n --cache-type-k q8_0 --cache-type-v q8_0 \\\n --host 127.0.0.1 --port 8080 --jinja\n```\n\n40 tokens per second compared to 8 is not a small upgrade. It is the difference between waiting for the model and actually using it.\n\nIt is not perfect. It calls tools semi accurately, so it gets the call right most of the time and not all of the time. It is also not that smart. I would not use it for coding related stuff, and I still reach for Ornith when I need a careful answer and can wait for it.\n\n## It runs hot\n\nOne thing nobody mentions in the benchmarks is heat. The MacBook Air has no fan, and running a local model keeps the chip busy the whole time it is generating. The laptop gets really hot.\n\nSo I use a laptop fan under it. If you plan to run local models on an Air for more than a quick question, get one. It is a cheap fix, and I would not run long sessions without it.\n\n## If you don't want the terminal\n\nEverything above is `llama-server` commands, and that is not how most people want to use AI. For a normal consumer, I think the Unsloth desktop app is a really good way to run local AI.\n\nIt gives you a friendly UI, and underneath it uses llama.cpp with optimized flags. So you get roughly what I set up by hand in this post, without having to learn what a KV cache is.\n\nThe chat also has a free local search tool, which is really useful. A small model does not know much on its own, and letting it search covers a lot of that gap.\n\n## Conclusion\n\nOn a 16GB MacBook Air, the limit is not really whether a model fits. A 9B model fits. The limit is whether it is fast enough and has enough context left over to be worth using.\n\nHere is where I landed:\n\n- **Ornith 9B** when I need accuracy. Good tool calls, smart, 6 to 8 tokens per second.\n- **Ling 3.0 Tiny** for everything else. Around 40 tokens per second, lots of context, semi accurate tool calls.\n- **LFM 2.5 2.6B** is not worth it for my use.\n- **A laptop fan** under the Air, whichever model is running.\n- **The Unsloth desktop app** if you want all of this without the terminal.\n\nI think the MoE approach is the sweet spot for local AI right now. Keep the total parameters reasonably high, activate only a small part of them per token, and a normal laptop can run it at a speed that feels usable. It is not going to replace a cloud model for coding. But it runs on the laptop I already own, offline, for free, and that is a good first step for consumer accessible AI.\n","html","

Running Local AI on a 16GB MacBook Air

My laptop is an M4 MacBook Air with 16GB of unified memory. For local AI that is not much. Most of the setups you see online have 64GB or more, or a desktop with a big GPU. But 16GB is what a normal person actually buys, so I wanted to know what local hosting looks like on this kind of machine, not on a workstation.

Short version: a 9B model is smart enough but too slow, and a small MoE model turned out to be the sweet spot.

The setup

I used llama.cpp on macOS. llama-server pulls a GGUF straight from Hugging Face and serves it on a local port, so trying a new model is one command.

This is the command for the 9B model I ended up preferring:

llama-server -hf ornith-ai/Ornith-1.5-9B-GGUF:Q4_K_M \\\n  -ngl 99 -np 2 -c 49152 -fa on --temp 0.6 \\\n  --cache-type-k q8_0 --cache-type-v q8_0 --no-mmproj \\\n  --host 127.0.0.1 --port 8080 --jinja\n

Most of these flags are there because of the 16GB limit.

-ngl 99 puts every layer on the GPU
-c is the context size, and it is the number I kept fighting with
-np is the number of parallel slots
-fa on turns on flash attention
--cache-type-k q8_0 --cache-type-v q8_0 quantizes the KV cache, which saves memory so more context fits
--no-mmproj skips the vision part, because I only need text
--jinja uses the model's own chat template, which tool calling needs

Everything is a Q4_K_M quant. On 16GB there is no room for anything bigger at this model size.

The 9B models

I tried four of them. They are all the same size, so the commands are almost identical.

Qwen 3.5 9B (unsloth/Qwen3.5-9B-GGUF). The base model, and my baseline.
OmniCoder 9B (Tesslate/OmniCoder-9B-GGUF). An agent fine-tune.
Ornith 1.5 9B (ornith-ai/Ornith-1.5-9B-GGUF). Another agent fine-tune, and the one I prefer.
Qwen 3.5 9B Uncensored (HauhauCS/Qwen3.5-9B-Uncensored-HauhauCS-Aggressive). An uncensored fine-tune. I ran this one at --temp 0.9, the rest at 0.6.

Ornith is pretty good. It calls tools accurately and it is smart. If I only cared about the quality of the answers, I would stop here.

1.5 is the newer release of Ornith. It is the same size as 1.0, so it needs the same memory, and its model card reports small gains over 1.0 across the board: 70.6 against 69.4 on SWE-bench Verified, and 46.2 against 43.1 on Terminal-Bench 2.1.

The problem is speed. A 9B model on this laptop runs at about 8 tokens per second, and it drops to around 6 when the context fills up. That is fine for one question. It is painful for anything agentic, where the model reads tool output, thinks, calls another tool, and does that ten times in a row.

The other problem is context. A 9B model already takes a big part of the 16GB, so there is not much left. I ran most of them at 32k, and pushed Ornith to 49k. That sounds like a lot until an agent starts reading files.

The tiny one that was not useful

I also tried going the other way with LFM 2.5 2.6B.

llama-server -hf LiquidAI/LFM2.5-2.6B-GGUF:BF16 \\\n  -ngl 99 -c 131072 -np 3 -fa on \\\n  --temp 0.1 --top-k 50 --repeat-penalty 1.1 \\\n  --host 127.0.0.1 --port 8080\n

It is small enough that I could run it unquantized with a 131k context and three slots. But it was not useful for what I wanted. Having a lot of context does not help when the model cannot do much with it.

Ling 3.0 Tiny

Then I found Ling 3.0 Tiny. It is a lightweight hybrid reasoning MoE model with 7.9B total parameters, but only 1.3B of them are activated per token.

That one detail changes everything on this hardware. The model has the knowledge of a roughly 8B model, but each token only costs about as much compute as a 1.3B model. With a Q4 quant it runs at around 40 tokens per second on my Air, and it can fit a lot of context.

llama-server -hf inclusionAI/Ling-3.0-tiny-GGUF:Q4_K_M \\\n  -ngl 99 -c 65536 -np 1 -fa on --temp 0.6 \\\n  --cache-type-k q8_0 --cache-type-v q8_0 \\\n  --host 127.0.0.1 --port 8080 --jinja\n

40 tokens per second compared to 8 is not a small upgrade. It is the difference between waiting for the model and actually using it.

It is not perfect. It calls tools semi accurately, so it gets the call right most of the time and not all of the time. It is also not that smart. I would not use it for coding related stuff, and I still reach for Ornith when I need a careful answer and can wait for it.

It runs hot

One thing nobody mentions in the benchmarks is heat. The MacBook Air has no fan, and running a local model keeps the chip busy the whole time it is generating. The laptop gets really hot.

So I use a laptop fan under it. If you plan to run local models on an Air for more than a quick question, get one. It is a cheap fix, and I would not run long sessions without it.

If you don't want the terminal

Everything above is llama-server commands, and that is not how most people want to use AI. For a normal consumer, I think the Unsloth desktop app is a really good way to run local AI.

It gives you a friendly UI, and underneath it uses llama.cpp with optimized flags. So you get roughly what I set up by hand in this post, without having to learn what a KV cache is.

The chat also has a free local search tool, which is really useful. A small model does not know much on its own, and letting it search covers a lot of that gap.

Conclusion

On a 16GB MacBook Air, the limit is not really whether a model fits. A 9B model fits. The limit is whether it is fast enough and has enough context left over to be worth using.

Here is where I landed:

Ornith 9B when I need accuracy. Good tool calls, smart, 6 to 8 tokens per second.
Ling 3.0 Tiny for everything else. Around 40 tokens per second, lots of context, semi accurate tool calls.
LFM 2.5 2.6B is not worth it for my use.
A laptop fan under the Air, whichever model is running.
The Unsloth desktop app if you want all of this without the terminal.

I think the MoE approach is the sweet spot for local AI right now. Keep the total parameters reasonably high, activate only a small part of them per token, and a normal laptop can run it at a speed that feels usable. It is not going to replace a cloud model for coding. But it runs on the laptop I already own, offline, for free, and that is a good first step for consumer accessible AI.

\n","projects",{"_7":36,"_27":135},[37,60,70,82,94,105,114,125],{"_10":38,"_12":39,"_40":41,"_42":43,"_50":51,"_54":55,"_14":56,"_57":58,"_26":59},"cool-shift","Cool Shift","description","A hackathon MVP of a personal energy assistant for Hong Kong households that turns smart meter data and a time-of-use tariff into three daily actions, each with a HK$ saving attached.","technologies",[44,45,46,47,48,49],"TypeScript","Next.js","React","Tailwind CSS","three.js","Leaflet","links",{"_52":53},"github","https://github.com/Chris4496/cool-shift","featured",true,"2026-10-04","status","completed","/images/coolshift-1.webp",{"_10":61,"_12":62,"_40":63,"_42":64,"_50":66,"_54":55,"_14":68,"_57":58,"_26":69},"carego-plus","CAREGO+","An AI-assisted career dashboard that turns a student survey, a LEGO reflection video, and optional teacher and peer reports into an exportable career development report.",[44,45,46,47,65],"Gemini",{"_52":67},"https://github.com/Chris4496/carego-plus","2026-07-14","/images/carego-1.webp",{"_10":71,"_12":72,"_40":73,"_42":74,"_50":78,"_54":55,"_14":80,"_57":58,"_26":81},"easy-checkout","Easy Checkout","An automated Checkout System with Vision Transformer (ViT), Vector Search and Computer Vision",[75,76,77],"Python","PyTorch","timm",{"_52":79},"https://github.com/Chris4496/EasyCheckout/","2026-01-15","/images/check-1.webp",{"_10":83,"_12":84,"_40":85,"_42":86,"_50":88,"_54":55,"_14":92,"_57":58,"_26":93},"graduation-playbill","Graduation Digital Playbill","A responsive full-stack digital playbill website to replace paper programs for the annual graduation show. With comments feature allowing attendees to upload comments and share their thoughts.",[44,46,47,87],"Supabase",{"_89":90,"_91":90},"demo","https://2025-fss-graduation-show.netlify.app/","live","2025-07-06","/images/grad-1.webp",{"_10":95,"_12":96,"_40":97,"_42":98,"_50":100,"_54":102,"_14":103,"_57":58,"_26":104},"northlens","NorthLens","A GenAI participatory-planning prototype for Hong Kong's Northern Metropolis that answers residents' questions from cited official sources and turns their feedback into a dashboard for planners.",[44,45,46,47,65,87,99,49],"pgvector",{"_52":101},"https://github.com/Chris4496/Northlens",false,"2026-09-30","/images/northlens-1.webp",{"_10":106,"_12":107,"_40":108,"_42":109,"_50":112,"_54":102,"_14":113,"_57":58,"_26":-7},"workout-tracker","Workout Tracker","A mobile-friendly web-app that tracks workouts and keeps records",[110,111],"Svelte","Javascript",{},"2023-06-06",{"_10":115,"_12":116,"_40":117,"_42":118,"_50":121,"_54":102,"_14":124,"_57":58,"_26":-7},"vocab-exercise-generator","Vocab Exercise Generator","A simple web-app that generates fill-in-the-blank sentence exercises based on dictionaries' examples for weaker English learners",[75,119,120,110,111],"BeautifulSoup4","FastAPI",{"_52":122,"_89":123,"_91":123},"https://github.com/Chris4496/VocabSentenceGeneratorFront","https://vocabgen.chriskwok.dev","2022-11-12",{"_10":126,"_12":127,"_40":128,"_42":129,"_50":131,"_54":102,"_14":134,"_57":58,"_26":-7},"the-dictionary-hub","The Dictionary Hub","A web-based dictionary utilizes web scraping from sources like Cambridge, Oxford, and Merriam-Webster, providing a seamless, convenient and ad-free user experience.",[75,119,120,46,44,130],"Docker",{"_52":132,"_89":133,"_91":133},"https://github.com/Chris4496/TheDictionaryHub/","https://dictionary.chriskwok.dev/","2022-07-30",{"_38":136,"_61":139,"_71":142,"_83":145,"_95":148,"_106":151,"_115":155,"_126":158},{"_10":38,"_12":39,"_40":41,"_42":43,"_50":51,"_54":55,"_14":56,"_57":58,"_26":59,"_30":137,"_32":138},"# Cool Shift\nCool Shift is a hackathon MVP my team and I built for a challenge sponsored by CLP. It is a phone-sized web app that tells a Hong Kong household when to cool the flat, when to charge the car, and when to run the dryer, and puts a dollar figure next to each one. The tagline is \"Small actions. Everyday value.\" It is an independent concept. It is not affiliated with or endorsed by CLP, and all the data in it is mock data.\n\n## Project Overview\nThe app is nine routes inside a 430px phone shell. Home shows the weather, the humidity, and three tips for today. Insights breaks down yesterday's usage and the latest bill. Ask is a chat screen. Cooling, Charging, and Budget each handle one decision. Impact and Rewards cover the community and the points side. The last route, `/pitch`, is the 12-slide deck we presented from, so the demo and the slides lived in the same tab.\n\nThere is no backend. A mock data layer stands in for the smart meter, the tariff, the weather, the bill, and the partner offers. A rules engine computes every figure from that data. Points, missions, the budget, and the language setting live in `localStorage`.\n\n## Motivation\nThe brief was about households that only meet their electricity once a month, as a bill. Smart meters are already installed and a time-of-use tariff makes the evening expensive, but a chart of kWh does not tell anyone what to do at 7 PM on a humid day.\n\nWe framed the product around five questions a customer would actually ask. Why is my bill increasing? When should I run my appliances? How do I charge an EV off-peak? How do I save without losing comfort? Which action fits my home? Every screen had to answer one of them.\n\nThe other decision was about the AI part. We did not want a chatbot that makes up a saving. So the rule for the build was that the numbers are calculated and the language only explains them. In a real deployment the chat would be a language model. It would read the question, pick the right calculation, and write the answer in plain language. In this MVP that part is keyword matching, and the engine underneath is deterministic. The spot where the model plugs in is marked in the code. For a demo, I would rather show an honest rules engine than a chat that sounds confident about a number it invented.\n\n## Features\n• **Three daily tips**
\nHome shows three actions for today and stops there. They appear one at a time, and tapping the mascot brings up the next. Cool the living room at 7:30 PM at 25.5°C. Charge the EV after 11 PM. Run the dryer after 9 PM. Each tip carries a saving range in HK$ and the kWh it moves out of the peak band.\n![Home](coolshift-2.webp \"width=350\")\n\n• **Insights and bill explainer**
\nYesterday's usage is drawn hour by hour against the peak tariff window. Below it, the June bill of HK$642 is compared with last month's HK$518, and the HK$124 difference is split line by line: cooling, EV charging at peak, the water heater, and everything else.\n![Insights](coolshift-3.webp \"width=350\")\n\n• **Ask**
\nA chat screen with quick chips for the common questions. Answers can attach a card, like the bill breakdown or tonight's plan with a \"how this was calculated\" section. The mission check-in reads the real app state, so if you complete a mission on the Rewards page and come back, the answer changes. In the demo the replies are matched by keyword. In a real deployment a language model would sit here and handle questions the chips do not cover.\n![Ask](coolshift-4.webp \"width=350\")\n\n• **Comfort-first cooling**
\nThe cooling plan holds 25.5°C with a fan and explains why. It has guardrails. It never suggests cutting cooling during a Very Hot Weather Warning or for vulnerable users.\n\n• **Smart charging**
\nA 3D car turns slowly above a target slider. The schedule sits inside the 11 PM to 7 AM off-peak window, at HK$1.06 per kWh against HK$1.87 at peak. For a 22 kWh top-up that comes to HK$16 to 18 saved per charge.\n![Charging](coolshift-5.webp \"width=350\")\n\n• **Budget**
\nA monthly budget slider with a pace bar, a projected month-end bill, a daily allowance, and alerts at 50, 80, and 100 percent. This one is aimed at bill shock.\n![Budget](coolshift-6.webp \"width=350\")\n\n• **Rewards and partners**
\nMissions earn points. Points are redeemed for partner offers shown on a real map of Sha Tin and in a list. Points can also be put into illustrative clean-energy funds.\n![Rewards](coolshift-7.webp \"width=350\")\n\n• **Community impact**
\nA personal impact summary, a shared goal for the building, an anonymised leaderboard, and a group challenge.\n![Impact](coolshift-8.webp \"width=350\")\n\n• **Watt-son**
\nA mascot you raise. Every point earned also mints one Frosty snack. Feeding gives XP, levels unlock stages and outfits. It is the least serious part of the app.\n![Watt-son](coolshift-9.webp \"width=350\")\n\n• **Traditional Chinese and simple mode**
\nA toggle switches the whole app between English and Traditional Chinese, including the chat replies. Simple mode enlarges the entire interface for users who need bigger text. The app also installs as a PWA and opens offline.\n![Chinese and simple mode](coolshift-10.webp \"width=350\")\n\n## Technical Architecture\n### Frontend\n- Next.js 14 App Router with React 18 and TypeScript, built fully static\n- Tailwind CSS with a small monochrome component set: cards, navigation, and hand-written SVG charts\n- A mobile-first shell capped at 430px, so it renders as a phone on any screen\n\n### Data and rules engine\n- `lib/data.ts` holds the mock smart meter readings, the tariff bands, the weather, the bill, the missions, the partners, and the building community, kept consistent with each other\n- `lib/engine.ts` computes the tips, the bill explanation, the budget projection, tonight's plan, and the chat replies from that data\n- Savings are shown as ranges, and a tip reads the tariff for its own hour, so changing a rate in the data changes every figure that depends on it\n\n### State\n- One React context holds points, budget, mission progress, vouchers, the points portfolio, the pet, the language, and simple mode\n- Everything persists under a single `localStorage` key, and clearing that key resets the demo\n\n### Extras\n- three.js for the car, loaded lazily so only the Charging page pays for it\n- Leaflet with OpenStreetMap tiles for the partner map, with no API key\n- A service worker that serves pages network-first and hashed assets cache-first\n\n## Challenges and Solutions\n**Keeping the numbers honest** was the main design problem. It is easy to type \"save HK$30 a month\" into a card. It is harder when the chat, the tip card, the charging page, and the pitch deck all have to agree. The fix was to stop writing figures in the UI. The charging saving is one function: energy needed times the gap between the peak and off-peak rate. The tip, the chat reply, and the charging page all call it. The chat itself is keyword matching on the question, in both languages, that picks which calculation to explain. A language model would replace that matching in production, and it would still be handed the same computed figures.\n\n**Simple mode did nothing at first.** The toggle set a larger font size on the body, and the page looked exactly the same, because the app sizes its text in fixed pixels. I switched to `zoom` on the phone column. That scaled everything, and then the column overflowed sideways. So the max width is divided by the zoom factor to keep the same width on screen. The Ask page broke again, because it is locked to the viewport height, and its input bar slid under the bottom nav. Its height is divided by the same factor.\n\n**Two languages in a weekend.** A translation file with keys would have meant naming a few hundred strings. Page copy uses an inline helper instead, `t(en, zh)`, so the English and the Chinese sit next to each other where they are used. The data fixtures carry a `zh` block that is merged over the English fields. It is not how I would do it for ten languages. For two, it meant nobody had to leave the file they were working in.\n\n**The map and the car were both drawings before they were real.** The first partner map was an illustration, so moving a shop meant redrawing it. It became a Leaflet map with partners stored as real coordinates, and the tiles are greyed out so the pins carry the meaning. The car went the same way, from a flat infographic to a three.js model. That model is heavy, so the component is imported dynamically and the battery bar stays in plain HTML, which keeps it in sync with the slider without touching the WebGL scene.\n\n**A service worker during a hackathon is a trap.** Development builds are not hashed, so a caching worker happily serves yesterday's code. The worker only registers in production, and the cache name carries a version that gets bumped when the strategy changes.\n\n## Conclusion\nCool Shift is a demo, and I think it is an honest one. Every figure on screen can be traced back to a meter reading and a tariff rate, even though the meter is fake. The scope is wide for a weekend. Nine routes is a lot, and a few of them are thinner than the others.\n\nThe next step would be the part we left for a real deployment. Swap the keyword matching for a language model, so the assistant can take any question, and keep the model away from the arithmetic. Replace the mock layer with real interval data from a meter. Then run the pilot from the proposal: households with smart meters, a matched control group, and success measured in kWh shifted and dollars saved, not in how many messages people send.\n\nThe code is on GitHub, along with the proposal and the pitch notes.\n","

Cool Shift

Cool Shift is a hackathon MVP my team and I built for a challenge sponsored by CLP. It is a phone-sized web app that tells a Hong Kong household when to cool the flat, when to charge the car, and when to run the dryer, and puts a dollar figure next to each one. The tagline is "Small actions. Everyday value." It is an independent concept. It is not affiliated with or endorsed by CLP, and all the data in it is mock data.

Project Overview

The app is nine routes inside a 430px phone shell. Home shows the weather, the humidity, and three tips for today. Insights breaks down yesterday's usage and the latest bill. Ask is a chat screen. Cooling, Charging, and Budget each handle one decision. Impact and Rewards cover the community and the points side. The last route, /pitch, is the 12-slide deck we presented from, so the demo and the slides lived in the same tab.

There is no backend. A mock data layer stands in for the smart meter, the tariff, the weather, the bill, and the partner offers. A rules engine computes every figure from that data. Points, missions, the budget, and the language setting live in localStorage.

Motivation

The brief was about households that only meet their electricity once a month, as a bill. Smart meters are already installed and a time-of-use tariff makes the evening expensive, but a chart of kWh does not tell anyone what to do at 7 PM on a humid day.

We framed the product around five questions a customer would actually ask. Why is my bill increasing? When should I run my appliances? How do I charge an EV off-peak? How do I save without losing comfort? Which action fits my home? Every screen had to answer one of them.

The other decision was about the AI part. We did not want a chatbot that makes up a saving. So the rule for the build was that the numbers are calculated and the language only explains them. In a real deployment the chat would be a language model. It would read the question, pick the right calculation, and write the answer in plain language. In this MVP that part is keyword matching, and the engine underneath is deterministic. The spot where the model plugs in is marked in the code. For a demo, I would rather show an honest rules engine than a chat that sounds confident about a number it invented.

Features

• Three daily tips
\nHome shows three actions for today and stops there. They appear one at a time, and tapping the mascot brings up the next. Cool the living room at 7:30 PM at 25.5°C. Charge the EV after 11 PM. Run the dryer after 9 PM. Each tip carries a saving range in HK$ and the kWh it moves out of the peak band.\n $\"Home\"$

• Insights and bill explainer
\nYesterday's usage is drawn hour by hour against the peak tariff window. Below it, the June bill of HK$642 is compared with last month's HK$518, and the HK$124 difference is split line by line: cooling, EV charging at peak, the water heater, and everything else.\n $\"Insights\"$

• Ask
\nA chat screen with quick chips for the common questions. Answers can attach a card, like the bill breakdown or tonight's plan with a "how this was calculated" section. The mission check-in reads the real app state, so if you complete a mission on the Rewards page and come back, the answer changes. In the demo the replies are matched by keyword. In a real deployment a language model would sit here and handle questions the chips do not cover.\n $\"Ask\"$

• Comfort-first cooling
\nThe cooling plan holds 25.5°C with a fan and explains why. It has guardrails. It never suggests cutting cooling during a Very Hot Weather Warning or for vulnerable users.

• Smart charging
\nA 3D car turns slowly above a target slider. The schedule sits inside the 11 PM to 7 AM off-peak window, at HK$1.06 per kWh against HK$1.87 at peak. For a 22 kWh top-up that comes to HK$16 to 18 saved per charge.\n $\"Charging\"$

• Budget
\nA monthly budget slider with a pace bar, a projected month-end bill, a daily allowance, and alerts at 50, 80, and 100 percent. This one is aimed at bill shock.\n $\"Budget\"$

• Rewards and partners
\nMissions earn points. Points are redeemed for partner offers shown on a real map of Sha Tin and in a list. Points can also be put into illustrative clean-energy funds.\n $\"Rewards\"$

• Community impact
\nA personal impact summary, a shared goal for the building, an anonymised leaderboard, and a group challenge.\n $\"Impact\"$

• Watt-son
\nA mascot you raise. Every point earned also mints one Frosty snack. Feeding gives XP, levels unlock stages and outfits. It is the least serious part of the app.\n $\"Watt-son\"$

• Traditional Chinese and simple mode
\nA toggle switches the whole app between English and Traditional Chinese, including the chat replies. Simple mode enlarges the entire interface for users who need bigger text. The app also installs as a PWA and opens offline.\n $\"Chinese$

Technical Architecture

Frontend

Next.js 14 App Router with React 18 and TypeScript, built fully static
Tailwind CSS with a small monochrome component set: cards, navigation, and hand-written SVG charts
A mobile-first shell capped at 430px, so it renders as a phone on any screen

Data and rules engine

lib/data.ts holds the mock smart meter readings, the tariff bands, the weather, the bill, the missions, the partners, and the building community, kept consistent with each other
lib/engine.ts computes the tips, the bill explanation, the budget projection, tonight's plan, and the chat replies from that data
Savings are shown as ranges, and a tip reads the tariff for its own hour, so changing a rate in the data changes every figure that depends on it

State

One React context holds points, budget, mission progress, vouchers, the points portfolio, the pet, the language, and simple mode
Everything persists under a single localStorage key, and clearing that key resets the demo

Extras

three.js for the car, loaded lazily so only the Charging page pays for it
Leaflet with OpenStreetMap tiles for the partner map, with no API key
A service worker that serves pages network-first and hashed assets cache-first

Challenges and Solutions

Keeping the numbers honest was the main design problem. It is easy to type "save HK$30 a month" into a card. It is harder when the chat, the tip card, the charging page, and the pitch deck all have to agree. The fix was to stop writing figures in the UI. The charging saving is one function: energy needed times the gap between the peak and off-peak rate. The tip, the chat reply, and the charging page all call it. The chat itself is keyword matching on the question, in both languages, that picks which calculation to explain. A language model would replace that matching in production, and it would still be handed the same computed figures.

Simple mode did nothing at first. The toggle set a larger font size on the body, and the page looked exactly the same, because the app sizes its text in fixed pixels. I switched to zoom on the phone column. That scaled everything, and then the column overflowed sideways. So the max width is divided by the zoom factor to keep the same width on screen. The Ask page broke again, because it is locked to the viewport height, and its input bar slid under the bottom nav. Its height is divided by the same factor.

Two languages in a weekend. A translation file with keys would have meant naming a few hundred strings. Page copy uses an inline helper instead, t(en, zh), so the English and the Chinese sit next to each other where they are used. The data fixtures carry a zh block that is merged over the English fields. It is not how I would do it for ten languages. For two, it meant nobody had to leave the file they were working in.

The map and the car were both drawings before they were real. The first partner map was an illustration, so moving a shop meant redrawing it. It became a Leaflet map with partners stored as real coordinates, and the tiles are greyed out so the pins carry the meaning. The car went the same way, from a flat infographic to a three.js model. That model is heavy, so the component is imported dynamically and the battery bar stays in plain HTML, which keeps it in sync with the slider without touching the WebGL scene.

A service worker during a hackathon is a trap. Development builds are not hashed, so a caching worker happily serves yesterday's code. The worker only registers in production, and the cache name carries a version that gets bumped when the strategy changes.

Conclusion

Cool Shift is a demo, and I think it is an honest one. Every figure on screen can be traced back to a meter reading and a tariff rate, even though the meter is fake. The scope is wide for a weekend. Nine routes is a lot, and a few of them are thinner than the others.

The next step would be the part we left for a real deployment. Swap the keyword matching for a language model, so the assistant can take any question, and keep the model away from the arithmetic. Replace the mock layer with real interval data from a meter. Then run the pilot from the proposal: households with smart meters, a matched control group, and success measured in kWh shifted and dollars saved, not in how many messages people send.

The code is on GitHub, along with the proposal and the pitch notes.

\n",{"_10":61,"_12":62,"_40":63,"_42":64,"_50":66,"_54":55,"_14":68,"_57":58,"_26":69,"_30":140,"_32":141},"# CAREGO+\nCAREGO+ is a guided career workflow I built so a student ends up with a report, not a chat transcript. They fill in a short self-discovery survey, record a LEGO reflection, optionally add a teacher or peer write-up, and the app turns all of that into a career development report they can export as a PDF. It started as a competition demo. It still runs as a demo when the Gemini key is missing.\n\n## Project Overview\nThe app is a three-step dashboard. Intake scores vocational interests, career adaptability, and field of study. Challenge is where the student uploads a video of a LEGO model that represents who they are now. Report stays locked until those pieces exist, then Gemini writes a structured report: recommended clusters, strengths, risks, a learning environment, portfolio ideas, and a 30/60/90 day plan.\n\nProgress lives in the browser. `localStorage` holds the answers, the analysis, the follow-ups, the observer reports, and the finished report. There is no account and no database. The Next.js API routes only exist for the work that has to leave the browser: sending a video to Gemini, generating the report, and pulling text out of an uploaded PDF or Word file.\n\n## Motivation\nI wanted the report to be traceable. If the app recommends a pathway, that recommendation should come from a survey score, from something the student actually built and explained, and, when it exists, from what a teacher or peer wrote down. A score with a fixed paragraph at the end felt too thin for that. A free-form chat felt too easy to wander away from the evidence.\n\nThe LEGO step is borrowed from LEGO Serious Play. People explain themselves more clearly when they have an object to point at. The prompt asks the student to build their current self, including strengths, fears, and the obstacles around them, then record a short explanation. The survey goes into the same prompt as a short intake summary, so the video analysis knows which interests and which field of study it is talking about.\n\nThe other requirement was that a demo still has to finish. If the API key is missing, the video never finishes processing, or the model returns something unreadable, the route serves a written fallback and the UI says so. A demo analysis is labeled as a demo analysis.\n\n## Features\n• **Self-discovery intake**
\nThree pages of Likert questions. Vocational interests follow a Holland RIASEC-inspired set: Realistic, Investigative, Artistic, Social, Enterprising, Conventional. Career adaptability uses the four resources from Career Construction Theory: concern, control, curiosity, and confidence. The last page asks which field of study matches the student's actual classes. Results stay hidden until every page is submitted.\n![Intake survey](carego-2.webp)\n\n• **Scored profile**
\nOn submit, each coded answer is summed into a score. The page shows a top RIASEC blend, a primary field of study, and grouped bar charts for all three sections. Redoing the survey clears the challenge, the observer reports, and the generated report, because those were written for a profile that no longer exists.\n![Intake results](carego-3.webp)\n\n• **LEGO reflection challenge**
\nThe challenge page shows the build prompt, four reflection questions, and a drag-and-drop upload for MP4, MOV, or WebM. A side panel tracks whether the intake is ready, whether the video has been reviewed, and whether the follow-up answers are filled in.\n![LEGO challenge](carego-4.webp)\n\n• **Video analysis and follow-ups**
\nGemini returns a headline, a description of the video, observed themes, strengths, barriers, career signals, and three follow-up questions about the model. The student answers those questions before the report button unlocks. Uploading a new video throws away the old analysis and the old report.\n![Analysis and follow-ups](carego-5.webp)\n\n• **Teacher and peer reports**
\nThese are optional. A teacher or peer file can be PDF, DOCX, or plain text. The server extracts the text, the browser stores it, and that text is included the next time the career report is generated.\n![Teacher and peer reports](carego-6.webp)\n\n• **Career report and PDF export**
\nThe report page shows the executive summary, a profile interpretation, recommended clusters with a first experiment for each one, strengths, risks, three radar charts of the survey scores, a support strategy, portfolio projects, and a 30/60/90 plan. A guidance note stays on the page. The report is reflective guidance for career development. It is not a clinical diagnosis, a psychological assessment, or an official placement. Export PDF opens a print layout meant to be saved as a PDF, and the suggested filename comes from the report title.\n![Career report](carego-7.webp)\n![Survey radar charts](carego-8.webp)\n![Printable report](carego-9.webp)\n\n## Technical Architecture\n### Frontend\n- Next.js App Router with client pages, because every step reads and writes `localStorage`\n- React 19 and Tailwind CSS, with a small set of shadcn/ui controls\n- A dashboard shell with the three steps, Intake, Challenge, and Report, plus a light and dark theme\n\n### Scoring and state\n- RIASEC, adaptability, and study-field scores are sums of the Likert answers for that code\n- One storage key per piece of progress, so redoing an earlier step can clear the later ones without touching unrelated data\n- The report page checks a generated flag and shows a checklist of missing steps while that flag is false\n\n### API routes\n- `POST /api/analyze-video` uploads the video through the Gemini Files API, waits until the file is active, then asks for a JSON analysis\n- `POST /api/generate-report` sends the survey scores, the video analysis, the follow-up answers, and any teacher or peer text, and asks for a JSON report\n- `POST /api/extract-report-text` reads PDF, DOCX, and TXT uploads on the server\n- The model name comes from `GEMINI_MODEL`, and falls back to Gemini 3.1 Flash Lite\n- Both AI routes normalize the model text before it is saved. A fenced JSON block is unwrapped, missing fields are filled from the demo copy, and a response that cannot be parsed becomes the full fallback\n\n## Challenges and Solutions\n**Getting a video through Gemini** was the first real blocker. A video file is not ready to reference the moment the upload returns. The Files API has to finish processing it. The route uploads the file, polls every few seconds, and gives up after five minutes. If the file fails, times out, or the key is missing, the student still gets the demo analysis instead of a stuck spinner. After the model responds, the uploaded file is deleted. When the browser does not send a MIME type, the route infers one from the file extension, so MOV and WebM still reach the model.\n\n**Model output is not safe to render raw.** The prompt asks for JSON only. The model still wraps it in fences, or adds a sentence, or drops a field. I pull out the object, then check every field. A missing list is replaced with the default copy for that field. A completely unreadable response is replaced with the whole demo report. The badge on the page says whether the text came from Gemini or from that fallback, so a canned analysis cannot pass as a personal one.\n\n**The PDF is a printed page, and printed pages are fussy.** I used the browser print dialog, with a separate article that only shows up on paper. The on-screen report and the PDF are allowed to disagree. Radar labels collided along the bottom of the chart, so the print chart anchors those labels differently. Dark mode colors were printing as if the page was still dark, so the print styles force their own ink. Right before `window.print()`, the document title is set to the report name, which is what the browser offers as the filename. It took a few passes before a saved PDF looked like a report and not a screenshot of the dashboard.\n\n**Teacher and peer files** brought their own bundling problem. Reading a PDF pulled in a canvas package that Next did not want inside the server bundle. I marked `pdf-parse` and that canvas package as server external packages, and limited uploads to PDF, DOCX, and TXT. A file with no readable text returns an error and nothing is saved.\n\n## Conclusion\nCAREGO+ is a working demo of a career workflow I like. Collect a few different kinds of evidence, make the student answer follow-up questions about their own model, and only then write the report. The scoring stays simple on purpose. One Likert item per code is enough to steer a demo, and the guidance note is there so nobody treats the PDF like a counseling result.\n\nThe next step is to give the case a home outside one browser. A teacher should be able to open the same evidence the student built. If the survey is ever going to carry more weight, it needs a real inventory, with more than one item per code. And the video analysis should have to describe the model in the frame, so a generic reflection cannot stand in for the build the student actually made.\n\nThe hosted demo is no longer available, but the [source code is on GitHub](https://github.com/Chris4496/carego-plus).\n","

CAREGO+

CAREGO+ is a guided career workflow I built so a student ends up with a report, not a chat transcript. They fill in a short self-discovery survey, record a LEGO reflection, optionally add a teacher or peer write-up, and the app turns all of that into a career development report they can export as a PDF. It started as a competition demo. It still runs as a demo when the Gemini key is missing.

Project Overview

The app is a three-step dashboard. Intake scores vocational interests, career adaptability, and field of study. Challenge is where the student uploads a video of a LEGO model that represents who they are now. Report stays locked until those pieces exist, then Gemini writes a structured report: recommended clusters, strengths, risks, a learning environment, portfolio ideas, and a 30/60/90 day plan.

Progress lives in the browser. localStorage holds the answers, the analysis, the follow-ups, the observer reports, and the finished report. There is no account and no database. The Next.js API routes only exist for the work that has to leave the browser: sending a video to Gemini, generating the report, and pulling text out of an uploaded PDF or Word file.

Motivation

I wanted the report to be traceable. If the app recommends a pathway, that recommendation should come from a survey score, from something the student actually built and explained, and, when it exists, from what a teacher or peer wrote down. A score with a fixed paragraph at the end felt too thin for that. A free-form chat felt too easy to wander away from the evidence.

The LEGO step is borrowed from LEGO Serious Play. People explain themselves more clearly when they have an object to point at. The prompt asks the student to build their current self, including strengths, fears, and the obstacles around them, then record a short explanation. The survey goes into the same prompt as a short intake summary, so the video analysis knows which interests and which field of study it is talking about.

The other requirement was that a demo still has to finish. If the API key is missing, the video never finishes processing, or the model returns something unreadable, the route serves a written fallback and the UI says so. A demo analysis is labeled as a demo analysis.

Features

• Self-discovery intake
\nThree pages of Likert questions. Vocational interests follow a Holland RIASEC-inspired set: Realistic, Investigative, Artistic, Social, Enterprising, Conventional. Career adaptability uses the four resources from Career Construction Theory: concern, control, curiosity, and confidence. The last page asks which field of study matches the student's actual classes. Results stay hidden until every page is submitted.\n $\"Intake$

• Scored profile
\nOn submit, each coded answer is summed into a score. The page shows a top RIASEC blend, a primary field of study, and grouped bar charts for all three sections. Redoing the survey clears the challenge, the observer reports, and the generated report, because those were written for a profile that no longer exists.\n $\"Intake$

• LEGO reflection challenge
\nThe challenge page shows the build prompt, four reflection questions, and a drag-and-drop upload for MP4, MOV, or WebM. A side panel tracks whether the intake is ready, whether the video has been reviewed, and whether the follow-up answers are filled in.\n $\"LEGO$

• Video analysis and follow-ups
\nGemini returns a headline, a description of the video, observed themes, strengths, barriers, career signals, and three follow-up questions about the model. The student answers those questions before the report button unlocks. Uploading a new video throws away the old analysis and the old report.\n $\"Analysis$

• Teacher and peer reports
\nThese are optional. A teacher or peer file can be PDF, DOCX, or plain text. The server extracts the text, the browser stores it, and that text is included the next time the career report is generated.\n $\"Teacher$

• Career report and PDF export
\nThe report page shows the executive summary, a profile interpretation, recommended clusters with a first experiment for each one, strengths, risks, three radar charts of the survey scores, a support strategy, portfolio projects, and a 30/60/90 plan. A guidance note stays on the page. The report is reflective guidance for career development. It is not a clinical diagnosis, a psychological assessment, or an official placement. Export PDF opens a print layout meant to be saved as a PDF, and the suggested filename comes from the report title.\n $\"Career$ \n $\"Survey$ \n $\"Printable$

Technical Architecture

Frontend

Next.js App Router with client pages, because every step reads and writes localStorage
React 19 and Tailwind CSS, with a small set of shadcn/ui controls
A dashboard shell with the three steps, Intake, Challenge, and Report, plus a light and dark theme

Scoring and state

RIASEC, adaptability, and study-field scores are sums of the Likert answers for that code
One storage key per piece of progress, so redoing an earlier step can clear the later ones without touching unrelated data
The report page checks a generated flag and shows a checklist of missing steps while that flag is false

API routes

POST /api/analyze-video uploads the video through the Gemini Files API, waits until the file is active, then asks for a JSON analysis
POST /api/generate-report sends the survey scores, the video analysis, the follow-up answers, and any teacher or peer text, and asks for a JSON report
POST /api/extract-report-text reads PDF, DOCX, and TXT uploads on the server
The model name comes from GEMINI_MODEL, and falls back to Gemini 3.1 Flash Lite
Both AI routes normalize the model text before it is saved. A fenced JSON block is unwrapped, missing fields are filled from the demo copy, and a response that cannot be parsed becomes the full fallback

Challenges and Solutions

Getting a video through Gemini was the first real blocker. A video file is not ready to reference the moment the upload returns. The Files API has to finish processing it. The route uploads the file, polls every few seconds, and gives up after five minutes. If the file fails, times out, or the key is missing, the student still gets the demo analysis instead of a stuck spinner. After the model responds, the uploaded file is deleted. When the browser does not send a MIME type, the route infers one from the file extension, so MOV and WebM still reach the model.

Model output is not safe to render raw. The prompt asks for JSON only. The model still wraps it in fences, or adds a sentence, or drops a field. I pull out the object, then check every field. A missing list is replaced with the default copy for that field. A completely unreadable response is replaced with the whole demo report. The badge on the page says whether the text came from Gemini or from that fallback, so a canned analysis cannot pass as a personal one.

The PDF is a printed page, and printed pages are fussy. I used the browser print dialog, with a separate article that only shows up on paper. The on-screen report and the PDF are allowed to disagree. Radar labels collided along the bottom of the chart, so the print chart anchors those labels differently. Dark mode colors were printing as if the page was still dark, so the print styles force their own ink. Right before window.print(), the document title is set to the report name, which is what the browser offers as the filename. It took a few passes before a saved PDF looked like a report and not a screenshot of the dashboard.

Teacher and peer files brought their own bundling problem. Reading a PDF pulled in a canvas package that Next did not want inside the server bundle. I marked pdf-parse and that canvas package as server external packages, and limited uploads to PDF, DOCX, and TXT. A file with no readable text returns an error and nothing is saved.

Conclusion

CAREGO+ is a working demo of a career workflow I like. Collect a few different kinds of evidence, make the student answer follow-up questions about their own model, and only then write the report. The scoring stays simple on purpose. One Likert item per code is enough to steer a demo, and the guidance note is there so nobody treats the PDF like a counseling result.

The next step is to give the case a home outside one browser. A teacher should be able to open the same evidence the student built. If the survey is ever going to carry more weight, it needs a real inventory, with more than one item per code. And the video analysis should have to describe the model in the frame, so a generic reflection cannot stand in for the build the student actually made.

The hosted demo is no longer available, but the source code is on GitHub.

\n",{"_10":71,"_12":72,"_40":73,"_42":74,"_50":78,"_54":55,"_14":80,"_57":58,"_26":81,"_30":143,"_32":144},"# EasyCheckout\nEasyCheckout is my attempt at building an AI project that behaves like a real system instead of a one-off demo. The idea is simple, take a single image of multiple items on a counter, identify each product, and calculate the total price automatically. Under the hood, it’s a pipeline that combines classic computer vision preprocessing with modern deep learning embeddings and vector similarity search, wrapped in a PySide6 GUI so the whole thing is actually usable.\n\n## Project Overview\nAt a high level, EasyCheckout does two jobs.\nFirst, it finds individual product regions inside a cluttered scene. Second, it matches each cropped product against a small to medium inventory database and retrieves its metadata, specifically name and price, then sums everything into a cart total. I intentionally avoided training a closed-set classifier because I didn’t want a workflow where adding a new product means retraining a model and hoping accuracy doesn’t collapse. I wanted a system where adding products is closer to “add a reference image and update a CSV.” Which makes it easy to use and manage.\n\nThe end result is a modular Python project, a preprocessing module, a Vision Transformer feature extractor, a ChromaDB-backed vector database layer, a matcher that joins embeddings with product metadata, and a GUI that orchestrates the entire flow and visualizes the output. It’s not production-grade checkout automation, but if paired with real world hardware and replace the current GUI with a production one. I will be ready.\n\n## Motivation\nI built this because I wanted something practical with AI. I’ve done the “model predicts something in a jupyter notebook” type of projects before, and they’re fine for learning, but they don’t teach you what happens when real inputs are messy and every component depends on the previous one not failing. I also didn’t want to build something that already exists in a thousand identical GitHub repos. I wanted a project where the output is obvious to anyone watching, and where the constraints feel like real life, where lighting changes, objects overlap, and the system still needs to return something coherent.\n\n## Inspiration\nThe inspiration came from two places. The first is Uniqlo’s RFID checkout experience. It’s smooth because the identification problem is basically solved, every item carries a tag, and the checkout station just reads it. That’s not “AI recognition,” but the UX is perfect, put items down, get total.\n\nThe second is the A1 Bakery checkout systems where a camera looks at a tray and recognizes what’s on it. That idea stuck with me because it’s the opposite approach. Instead of relying on tags, the system tries to understand the image. It’s harder and less reliable, but it’s also much more flexible in scenarios where tagging is unrealistic. [A1 Bakery Article](https://www.thestandard.com.hk/breaking-news/article/195048/A-1-Bakery-announces-technological-breakthroughs-for-the-benefit-of-customers)\n\nEasyCheckout is me trying to expand the idea of using image recognition for checkout. But with any products you want, not only bread.\n\n## System Architecture\nThe pipeline is deliberately staged because each stage has a different failure mode and I wanted those failures to be debuggable. The process starts with image loading and normalization so the data is in a predictable shape. Then a product detector step segments the scene into individual regions using brightness-based thresholding and contour filtering, producing cropped images for each candidate product. Each crop goes into a feature extractor based on a Vision Transformer backbone, where I remove the classification head and treat the model as an embedding generator. Those embeddings are then queried against a ChromaDB collection that stores embeddings for the reference product images in the inventory. The matcher takes the nearest neighbor results, retrieves the associated product metadata from a CSV, and aggregates everything into a final list of detected items and a total price.\n\nThat “embeddings + vector search” choice is the core design decision. It turns the problem into retrieval rather than classification, which is a better fit for “small inventory that changes over time” and for a project where I want the onboarding story to be simple.\n\n## Features (What it can do in practice)\nIn practice, there are two ways to use it. The GUI is the main one. It lets you load an image from disk or capture one from a camera, run the full detection and matching pipeline, and see annotated results with bounding boxes and predicted labels. It also computes the total automatically based on matched items, and it can export the annotated output for record-keeping or debugging. The second way is a CLI batch mode that indexes product images from the products folder, processes a test folder, writes results into an output directory, and prints logs that make it obvious where things go wrong.\n\nPerformance-wise, the first run can be slow because model weights need to download and initialization costs are real. After that, it’s responsive enough for a demo. With a GPU, the inference step becomes much less of a bottleneck, but the preprocessing and data movement still matter.\n\nThese are both built for demo. The main processing logic is here, the only thing left for production is that it needs a sophisticated inventory system and the physical checkout setup.\n![Product Shots](check-4.webp)\n![Product Info](check-3.webp)\n![Demo UI](check-2.webp)\n\n## Market Analysis (What gap this fills)\nI’m not pretending this replaces a POS system. Barcode scanners are cheap and extremely reliable. RFID checkout is even smoother, but it requires tagged inventory and dedicated infrastructure. Human cashiers are flexible and handle edge cases effortlessly, but labor cost and throughput are constraints.\n\nA system like EasyCheckout makes sense in narrower conditions, small or curated inventories, predictable counter setups, and environments where you can control lighting and camera placement. Bakeries are the obvious example because items are placed in consistent ways and RFID tagging pastries is not realistic. Small pop-up stores or internal prototypes are another case, where the main goal is to validate whether visual recognition is even feasible for the product set.\n\n## Challenges and Solutions\n**Separating multiple products from a single scan** was the first real blocker. In theory, instance segmentation models should solve this immediately, so that’s where I started. In practice, they were a bad fit for my setup. Most segmentation approaches expect labeled data, and I didn’t have it. The whole point of my system is that I don’t reliably know the “true” product name at capture time, and even when I did have a label, the segmentation quality still wasn’t consistent, especially with transparent packaging where boundaries are ambiguous and the model behaves like it’s guessing.\n\nAfter that, I went through the usual computer vision toolbox. I tried edge detection-based pipelines, then color-based methods, and a bunch of variations in between. None of them were stable enough for my scenes. Edges break on low-contrast items and reflective surfaces, while color methods collapse when packaging colors are similar or lighting shifts. What finally worked best for my constraints was a brightness-difference approach. I put a light board as the background, then detect “product” regions as the parts that are noticeably darker than the background. From there, I crop those regions and pass them downstream. Transparent products were still annoying because their detected regions can fragment or partially overlap, so I added a simple rule which is to merge overlapping boxes so at least the system doesn’t split one item into several nonsense crops. It’s not elegant, but it’s the most reliable solution I found without labels.\n\n**Choosing the vision model** was the second major decision. My first attempt was to use standard classification models, and the limitation became obvious quickly, classification assumes fixed classes and it doesn’t naturally map to “identify this exact SKU in my inventory.” My inventory items are specific and sometimes visually similar, and I needed matching, not just category prediction. That’s why I moved to a Vision Transformer feature-extraction approach. The goal wasn’t “predict class,” it was “generate an embedding that can distinguish fine-grained differences,” then retrieve the closest product from the database. After testing different sizes, I settled on **DINOv3 Base** at around **87.6M parameters**, described as a distillation of **DINOv3 7B**. The practical reason was boring but important, it can run comfortably on CPU hardware, which matters if this is ever going to resemble a real checkout kiosk instead of a GPU-only demo.\n\n**Overlapping products** is still the problem I haven’t solved. Because my cropping depends on brightness difference, two products that overlap can become a single connected “dark region,” and the system treats them as one item. That breaks everything downstream because one crop can only match to one product embedding, and the pricing becomes wrong immediately. I don’t have a clean fix for this yet. Right now, my system works best when items are placed with minimal overlap, which is a limitation I’m not going to pretend is acceptable for a real checkout scenario.\n\n## Conclusion\nEasyCheckout is a working prototype that demonstrates an approach I like. In a controlled environment, it produces results that feel like the beginning of a real checkout experience.\n\nRight now, the brightness-based cropping approach is the main reason the system works at all, and also the main reason it can fail badly. In a controlled setup with a light board background, it is simple, fast, and surprisingly reliable. The question is whether I should keep investing in it or replace it entirely. If I can make it handle overlap and transparency more consistently without turning the pipeline into a fragile mess of thresholds, then it’s worth keeping because it’s cheap to run and easy to explain. If overlap remains a hard failure mode, then I should stop patching it and switch to a detection/segmentation approach that is designed for separating touching objects.\n\nThe next step is to stop treating this like “an algorithm on my laptop” and build the full kiosk setup. That means locking down the camera position, distance, background, and lighting as part of the system design, not as an afterthought. If the environment is part of the product, then engineering the environment is not cheating—, it’s literally how you make the pipeline stable.\n\nAfter that, I need to test it in more extreme scenarios on purpose, harsher lighting, shadows, reflective packaging, transparent products, motion blur from quick scans, different camera sensors, and especially overlapping items. If it survives those tests with only small degradations, then the brightness approach is validated. If it collapses, then the conclusion is clear that the segmentation stage needs to be replaced, and the rest of the system should be treated as the reusable part that plugs into a better front end.","

EasyCheckout

EasyCheckout is my attempt at building an AI project that behaves like a real system instead of a one-off demo. The idea is simple, take a single image of multiple items on a counter, identify each product, and calculate the total price automatically. Under the hood, it’s a pipeline that combines classic computer vision preprocessing with modern deep learning embeddings and vector similarity search, wrapped in a PySide6 GUI so the whole thing is actually usable.

Project Overview

At a high level, EasyCheckout does two jobs.\nFirst, it finds individual product regions inside a cluttered scene. Second, it matches each cropped product against a small to medium inventory database and retrieves its metadata, specifically name and price, then sums everything into a cart total. I intentionally avoided training a closed-set classifier because I didn’t want a workflow where adding a new product means retraining a model and hoping accuracy doesn’t collapse. I wanted a system where adding products is closer to “add a reference image and update a CSV.” Which makes it easy to use and manage.

The end result is a modular Python project, a preprocessing module, a Vision Transformer feature extractor, a ChromaDB-backed vector database layer, a matcher that joins embeddings with product metadata, and a GUI that orchestrates the entire flow and visualizes the output. It’s not production-grade checkout automation, but if paired with real world hardware and replace the current GUI with a production one. I will be ready.

Motivation

I built this because I wanted something practical with AI. I’ve done the “model predicts something in a jupyter notebook” type of projects before, and they’re fine for learning, but they don’t teach you what happens when real inputs are messy and every component depends on the previous one not failing. I also didn’t want to build something that already exists in a thousand identical GitHub repos. I wanted a project where the output is obvious to anyone watching, and where the constraints feel like real life, where lighting changes, objects overlap, and the system still needs to return something coherent.

Inspiration

The inspiration came from two places. The first is Uniqlo’s RFID checkout experience. It’s smooth because the identification problem is basically solved, every item carries a tag, and the checkout station just reads it. That’s not “AI recognition,” but the UX is perfect, put items down, get total.

The second is the A1 Bakery checkout systems where a camera looks at a tray and recognizes what’s on it. That idea stuck with me because it’s the opposite approach. Instead of relying on tags, the system tries to understand the image. It’s harder and less reliable, but it’s also much more flexible in scenarios where tagging is unrealistic. A1 Bakery Article

EasyCheckout is me trying to expand the idea of using image recognition for checkout. But with any products you want, not only bread.

System Architecture

The pipeline is deliberately staged because each stage has a different failure mode and I wanted those failures to be debuggable. The process starts with image loading and normalization so the data is in a predictable shape. Then a product detector step segments the scene into individual regions using brightness-based thresholding and contour filtering, producing cropped images for each candidate product. Each crop goes into a feature extractor based on a Vision Transformer backbone, where I remove the classification head and treat the model as an embedding generator. Those embeddings are then queried against a ChromaDB collection that stores embeddings for the reference product images in the inventory. The matcher takes the nearest neighbor results, retrieves the associated product metadata from a CSV, and aggregates everything into a final list of detected items and a total price.

That “embeddings + vector search” choice is the core design decision. It turns the problem into retrieval rather than classification, which is a better fit for “small inventory that changes over time” and for a project where I want the onboarding story to be simple.

Features (What it can do in practice)

In practice, there are two ways to use it. The GUI is the main one. It lets you load an image from disk or capture one from a camera, run the full detection and matching pipeline, and see annotated results with bounding boxes and predicted labels. It also computes the total automatically based on matched items, and it can export the annotated output for record-keeping or debugging. The second way is a CLI batch mode that indexes product images from the products folder, processes a test folder, writes results into an output directory, and prints logs that make it obvious where things go wrong.

Performance-wise, the first run can be slow because model weights need to download and initialization costs are real. After that, it’s responsive enough for a demo. With a GPU, the inference step becomes much less of a bottleneck, but the preprocessing and data movement still matter.

These are both built for demo. The main processing logic is here, the only thing left for production is that it needs a sophisticated inventory system and the physical checkout setup.\n $\"Product$ \n $\"Product$ \n $\"Demo$

Market Analysis (What gap this fills)

I’m not pretending this replaces a POS system. Barcode scanners are cheap and extremely reliable. RFID checkout is even smoother, but it requires tagged inventory and dedicated infrastructure. Human cashiers are flexible and handle edge cases effortlessly, but labor cost and throughput are constraints.

A system like EasyCheckout makes sense in narrower conditions, small or curated inventories, predictable counter setups, and environments where you can control lighting and camera placement. Bakeries are the obvious example because items are placed in consistent ways and RFID tagging pastries is not realistic. Small pop-up stores or internal prototypes are another case, where the main goal is to validate whether visual recognition is even feasible for the product set.

Challenges and Solutions

Separating multiple products from a single scan was the first real blocker. In theory, instance segmentation models should solve this immediately, so that’s where I started. In practice, they were a bad fit for my setup. Most segmentation approaches expect labeled data, and I didn’t have it. The whole point of my system is that I don’t reliably know the “true” product name at capture time, and even when I did have a label, the segmentation quality still wasn’t consistent, especially with transparent packaging where boundaries are ambiguous and the model behaves like it’s guessing.

After that, I went through the usual computer vision toolbox. I tried edge detection-based pipelines, then color-based methods, and a bunch of variations in between. None of them were stable enough for my scenes. Edges break on low-contrast items and reflective surfaces, while color methods collapse when packaging colors are similar or lighting shifts. What finally worked best for my constraints was a brightness-difference approach. I put a light board as the background, then detect “product” regions as the parts that are noticeably darker than the background. From there, I crop those regions and pass them downstream. Transparent products were still annoying because their detected regions can fragment or partially overlap, so I added a simple rule which is to merge overlapping boxes so at least the system doesn’t split one item into several nonsense crops. It’s not elegant, but it’s the most reliable solution I found without labels.

Choosing the vision model was the second major decision. My first attempt was to use standard classification models, and the limitation became obvious quickly, classification assumes fixed classes and it doesn’t naturally map to “identify this exact SKU in my inventory.” My inventory items are specific and sometimes visually similar, and I needed matching, not just category prediction. That’s why I moved to a Vision Transformer feature-extraction approach. The goal wasn’t “predict class,” it was “generate an embedding that can distinguish fine-grained differences,” then retrieve the closest product from the database. After testing different sizes, I settled on DINOv3 Base at around 87.6M parameters, described as a distillation of DINOv3 7B. The practical reason was boring but important, it can run comfortably on CPU hardware, which matters if this is ever going to resemble a real checkout kiosk instead of a GPU-only demo.

Overlapping products is still the problem I haven’t solved. Because my cropping depends on brightness difference, two products that overlap can become a single connected “dark region,” and the system treats them as one item. That breaks everything downstream because one crop can only match to one product embedding, and the pricing becomes wrong immediately. I don’t have a clean fix for this yet. Right now, my system works best when items are placed with minimal overlap, which is a limitation I’m not going to pretend is acceptable for a real checkout scenario.

Conclusion

EasyCheckout is a working prototype that demonstrates an approach I like. In a controlled environment, it produces results that feel like the beginning of a real checkout experience.

Right now, the brightness-based cropping approach is the main reason the system works at all, and also the main reason it can fail badly. In a controlled setup with a light board background, it is simple, fast, and surprisingly reliable. The question is whether I should keep investing in it or replace it entirely. If I can make it handle overlap and transparency more consistently without turning the pipeline into a fragile mess of thresholds, then it’s worth keeping because it’s cheap to run and easy to explain. If overlap remains a hard failure mode, then I should stop patching it and switch to a detection/segmentation approach that is designed for separating touching objects.

The next step is to stop treating this like “an algorithm on my laptop” and build the full kiosk setup. That means locking down the camera position, distance, background, and lighting as part of the system design, not as an afterthought. If the environment is part of the product, then engineering the environment is not cheating—, it’s literally how you make the pipeline stable.

After that, I need to test it in more extreme scenarios on purpose, harsher lighting, shadows, reflective packaging, transparent products, motion blur from quick scans, different camera sensors, and especially overlapping items. If it survives those tests with only small degradations, then the brightness approach is validated. If it collapses, then the conclusion is clear that the segmentation stage needs to be replaced, and the rest of the system should be treated as the reusable part that plugs into a better front end.

\n",{"_10":83,"_12":84,"_40":85,"_42":86,"_50":88,"_54":55,"_14":92,"_57":58,"_26":93,"_30":146,"_32":147},"\n# Graduation Digital Playbill\nA responsive full-stack digital playbill website to replace paper programs for the annual graduation show, serving over 500 attendees. Enhancing the traditional program experience.\n## Project Overview\nBeing in the Class Representative Committee, I was asked to build a digital playbill website for the graduation show. Built it in a few days using React and with the help of AI.\n## Features\n• **Beautiful Interface**
Designed with Tailwind CSS for a theme-fitting, responsive layout that works across devices, from mobile phones to desktops.\n\n• **Interactive Comments Section**
Attendees can upload comments, share thoughts in real-time. Powered by Supabase.\n\n• **Cast Photos and Videos**
An integrated gallery showcasing cast photos and embedded videos, allowing users to view performer highlights, behind-the-scenes footage, and personal introductions. This feature adds a visual and interactive element, making the playbill more immersive and memorable.\n\n• **Event Schedule and Details**
A comprehensive display of the graduation schedule, including performer names, performance times, and show summary.\n## Technical Architecture\n### Backend\n- Supabase: provides a simple SQL database\n### Frontend\n- TypeScript: for static type checking and code organization\n- React: for building the user interface\n- Tailwind CSS: for easy styling\n## Lessons Learned\nThis is the first website that I built for a client, so I'm afraid that I might not have fully met the expectations. However, the experience was incredibly valuable and taught me a key lesson:\n### Time Management and Planning\nMost of the time was not spent building the website, but instead it was spent tweaking with the client. I provided a demo version of the website to the client to see if the styles meets the client's expectation and see if the features are what they want. Communication is crucial to ensure I can use my time effectively and the client gets what they want.\n## Impact and Results\nThe website was used by over **500 attendees** during the graduation show. By going digital, we were able to save money by replacing hundreds of printed paper programs, making the event more eco-friendly. The comments section became a highlight, with attendees leaving messages of congratulations and encouragement, which added a personal and interactive touch to the event. The school appreciated how easy it was to update the schedule and details without needing to reprint anything.\n\n## Conclusion\nIn conclusion, this is my first time where I actually get to work on a real world project, serving a purpose. I learned how to effectively communicate with someone and work together to achieve the desired and satisfactory outcome. It also gave me the confidence to tackle more complex projects in the future.","

Graduation Digital Playbill

A responsive full-stack digital playbill website to replace paper programs for the annual graduation show, serving over 500 attendees. Enhancing the traditional program experience.

Project Overview

Being in the Class Representative Committee, I was asked to build a digital playbill website for the graduation show. Built it in a few days using React and with the help of AI.

Features

• Beautiful Interface
Designed with Tailwind CSS for a theme-fitting, responsive layout that works across devices, from mobile phones to desktops.

• Interactive Comments Section
Attendees can upload comments, share thoughts in real-time. Powered by Supabase.

• Cast Photos and Videos
An integrated gallery showcasing cast photos and embedded videos, allowing users to view performer highlights, behind-the-scenes footage, and personal introductions. This feature adds a visual and interactive element, making the playbill more immersive and memorable.

• Event Schedule and Details
A comprehensive display of the graduation schedule, including performer names, performance times, and show summary.

Technical Architecture

Backend

Supabase: provides a simple SQL database

Frontend

TypeScript: for static type checking and code organization
React: for building the user interface
Tailwind CSS: for easy styling

Lessons Learned

This is the first website that I built for a client, so I'm afraid that I might not have fully met the expectations. However, the experience was incredibly valuable and taught me a key lesson:

Time Management and Planning

Most of the time was not spent building the website, but instead it was spent tweaking with the client. I provided a demo version of the website to the client to see if the styles meets the client's expectation and see if the features are what they want. Communication is crucial to ensure I can use my time effectively and the client gets what they want.

Impact and Results

The website was used by over 500 attendees during the graduation show. By going digital, we were able to save money by replacing hundreds of printed paper programs, making the event more eco-friendly. The comments section became a highlight, with attendees leaving messages of congratulations and encouragement, which added a personal and interactive touch to the event. The school appreciated how easy it was to update the schedule and details without needing to reprint anything.

Conclusion

In conclusion, this is my first time where I actually get to work on a real world project, serving a purpose. I learned how to effectively communicate with someone and work together to achieve the desired and satisfactory outcome. It also gave me the confidence to tackle more complex projects in the future.

\n",{"_10":95,"_12":96,"_40":97,"_42":98,"_50":100,"_54":102,"_14":103,"_57":58,"_26":104,"_30":149,"_32":150},"# NorthLens\nNorthLens 北覽 is a participatory-planning prototype I built for the Northern Metropolis, piloted on the Kwu Tung North New Development Area. A resident asks what the plan means for them and gets an answer where every claim is cited and tagged by how firm it is. Then they say what they think, by typing or by speaking, and a planner sees it grouped with everyone else's on a dashboard. The line I kept coming back to is that NorthLens doesn't ask AI to design Hong Kong. It uses AI to help Hong Kong design with its communities.\n\n## Project Overview\nThe app has two views. The resident view at `/` is where you pick a persona and a concern, ask a question in English or Traditional Chinese, and read the answer next to a map of the places it mentions. Below that are the Scenario Explorer and the Community Voice form. The planner view at `/dashboard` takes those submissions, anonymised and classified, and shows what people are worried about, who is worried, and where.\n\nThe knowledge base is small on purpose. It is 46 passages paraphrased from 23 public sources: Government press releases, Town Planning Board papers, LegCo replies, and MTR documents. Each passage carries a status. Completed, under construction, planned, proposal, under review, or superseded. That status follows the passage all the way to the screen.\n\nIt also runs with no keys at all. Without a Gemini key, retrieval falls back to keyword search and answers are composed from the retrieved passages by template. Without Supabase, feedback is written to a local JSON file. A status dot in the header shows which mode is live.\n\n## Motivation\nPlanning documents are public, but they are not readable. The answer to \"can my mother get to the new station\" is spread across an Outline Development Plan, a railway press release, and a LegCo reply, and some of those contradict each other because plans change. Kwu Tung North is a good example. The hospital that was originally planned there was superseded by a proposal in Ngau Tam Mei, and the site that was reserved is under review.\n\nThat is exactly where an ordinary chatbot is dangerous. It will repeat the old plan in a confident voice. So the rule for the build was that the model may only speak from passages it was handed, and a proposal must never read like a commitment.\n\nThe other half is the planner's side. A consultation produces hundreds of free-text submissions and somebody has to read them. I wanted the AI to do the sorting and a person to do the deciding. The AI proposes a category. A reviewer confirms it or corrects it. The original text is always kept.\n\n## Features\n• **Ask the plan**
\nPick one of three personas, a university student, a working adult, or a caregiver of an elderly parent, then pick a concern. The answer comes back in three parts: what may change, why it matters for you, and what is uncertain. Every claim has numbered citations and a status chip, so \"Under construction\" and \"Proposal · may change\" sit side by side in the same answer.\n![Ask the plan](northlens-2.webp)\n\n• **Plan map**
\nThe map highlights the stations, facilities, and routes that the answer cites. It uses the HKSAR Lands Department basemap, and the labels switch language with the rest of the app. The Northern Link is drawn as a dashed line because it is not built yet.\n![Plan map](northlens-3.webp)\n\n• **Scenario Explorer**
\nA \"living here\" view that lines up everyday needs, transport, healthcare, elderly care, education, employment, green space, and cross-border access, against what the plans actually say. Each row links to its passages and shows their status. Healthcare is the row worth reading, because that is where the superseded hospital plan shows up.\n![Scenario Explorer](northlens-4.webp)\n\n• **Community Voice**
\nTick the priorities that matter, then type or press Speak. Voice works in Cantonese, in English, and in a mix of both, so \"天橋一定要有 lift\" comes out the way it was said. Gemini transcribes the recording into the text box and the resident checks it before submitting. The audio is never stored. Names, phone numbers, HKID numbers, emails, and flat addresses are redacted before anything is classified or saved.\n![Community Voice](northlens-5.webp)\n\n• **Planner dashboard**
\nFilters for period, group, area, and live versus demo data. Above the fold are the headline numbers: concern rate, share from vulnerable groups, review coverage, how often reviewers agree with the AI's category, and voice share. An emerging concern banner names the issue and group with the most recent worry. Below that is a priority issues table with volume, sentiment, a 6-week trend, the 14-day change, and whether the related plan items are still open to change.\n![Planner dashboard](northlens-6.webp)\n\n• **Issue drill-down, heatmap, and hotspots**
\nOpening an issue shows suggested actions, the affected groups and areas, the related plan items with their sources, and quotes. A heatmap shows which groups worry about which issues, and a second map shows where the feedback clusters.\n![Heatmap](northlens-7.webp)\n\n• **AI briefing**
\nOne button writes a short briefing for the planner: a headline, up to three findings, and up to three follow-ups. It is written from the computed statistics and nothing else.\n![AI briefing](northlens-8.webp)\n\n• **Human review queue**
\nEach submission shows the AI's proposed theme beside the original text. A reviewer confirms it or picks another from a dropdown. Reviewed rows are marked, and the original text is never changed.\n![Review queue](northlens-9.webp)\n\n• **Exports**
\nA consultation report and a feedback report, each with a print layout and a CSV download. Exports only ever contain responses a person has confirmed in the review queue. If nothing in the current filter has been confirmed, the buttons are disabled.\n![Consultation report](northlens-10.webp)\n\n• **Traditional Chinese and guided tours**
\nThe 繁 toggle switches the whole flow, including the answers, the map labels, and the dashboard. Both views have a step-by-step tour that points at each section in turn.\n![Traditional Chinese](northlens-11.webp)\n\n## Technical Architecture\n### Frontend\n- Next.js 16 App Router with React 19 and TypeScript\n- Tailwind CSS v4\n- Leaflet through react-leaflet, with the Lands Department basemap from the GeoData Store, which needs no API key\n\n### Retrieval\n- Each passage is embedded as one document holding both its English and its Chinese text, so a question in either language can find it\n- Three modes, in order: pgvector in Supabase through a `match_kb_chunks` RPC, in-memory Gemini embeddings, and keyword search\n- The keyword scorer is BM25-style, with stemming for English and bigrams for Chinese, plus a small synonym table so that 輪椅 or \"difficulty walking\" reaches the footbridge passages\n- The final ranking is hybrid: 60% semantic, 25% keyword, and 15% for topics that match the chosen persona and concern\n- A question that asks about uncertainty gives a small boost to passages that are proposed, under review, or superseded\n\n### Answering and guardrails\n- Gemini returns JSON against a response schema: a summary, three lists of claims, and an insufficient-evidence flag\n- Citations to passages that were not retrieved are dropped\n- A claim is dropped if it contains a number that does not appear in the passages it cites\n- A claim's status is the weakest status among its sources\n- If nothing survives, the answer says the evidence is thin and stops there\n\n### Feedback pipeline\n- PII redaction by pattern, before classification and before storage\n- Gemini classifies each submission into zone, theme, stakeholder, sentiment, and a suggested issue, with every field constrained to an enum\n- The result is validated again on the server. If a field is missing or outside the enum, the rule-based classifier is used instead\n- An empty feedback table seeds itself with 50 synthetic responses, flagged as synthetic in the data and in the UI\n\n### Insights\n- All dashboard statistics are computed in plain TypeScript in `lib/insights.ts`. No model is involved\n- The priority score is concerned responses × (1 + half the share from vulnerable groups) × a trend factor between 0.75 and 1.25 taken from the 14-day change\n\n### Storage\n- Supabase Postgres with RLS on and no public policies. The keys are server-only\n- Without Supabase, `.data/feedback.json`, written through a promise queue and a temp-file rename\n\n## Challenges and Solutions\n**Keeping a proposal from sounding like a promise** was the main design problem. A prompt that says \"be careful about uncertain plans\" is a suggestion, and models ignore suggestions. So the status is not something the model writes. It comes from the passages. After the model answers, the server looks up every passage a claim cites and gives the claim the weakest status of the group. If a sentence leans on one station that is under construction and one footbridge that is only proposed, the chip says proposal. The model can phrase it however it likes. It cannot upgrade it.\n\n**Numbers were the other leak.** Dates and distances are what residents will plan around, and they are what a model rounds or misremembers. Every number in a claim is pulled out and compared with the numbers in the cited passages, in both languages. One number that is not there and the whole claim is dropped. The AI briefing on the dashboard uses the same check. The server writes a block of facts from the computed statistics, the model writes prose from it, and any finding with a number that is not in that block is removed before the planner sees it. It is a blunt rule and it throws away some good sentences. I would rather lose a sentence than show a figure nobody can trace.\n\n**The model invents speech when given silence.** Send a transcription model a recording of nothing and it does not return nothing. It returns a plausible sentence. For a tool that collects public opinion, that is a resident saying something they never said. There are three guards. The browser watches the microphone level while recording and counts the frames that actually contain sound, and a recording with too few never leaves the device. The server rejects clips that are too small to be real. And the response schema has a `speech` boolean, so the model has a way to say \"nobody spoke\" that is not an empty transcript. The transcript lands in the text box for the resident to check, never straight into the database.\n\n**Working with no keys** shaped more of the code than I expected. Every AI step needed a second path that was not embarrassing. Retrieval has the keyword scorer. Chinese has no spaces, so the tokenizer splits runs of characters into bigrams, and a stop list removes the bigrams that turn up in every planning question. Answers have a template composer that only uses the first sentence of each retrieved passage, and its output goes through the same citation check as Gemini's. Classification has rules. The voice button and the briefing are simply hidden, because those have no honest fallback.\n\n**The local file store was easy to break.** Two submissions arriving together could both read the file, both append, and one would overwrite the other. Writes now go through a single promise queue, and each write goes to a temp file that is renamed over the real one. A corrupt file is left alone and the request fails, because overwriting it with an empty list would quietly delete real feedback. There is a test for each of these: fifteen concurrent writes must all survive, a broken file must come out byte-for-byte the same, and an invalid review request must not touch the file at all.\n\n**Model output is input, and it gets validated like input.** The classifier test feeds in a response with two extra properties, a replacement `text` and a replacement `id`, and checks that neither reaches the stored record. Only the six expected fields are copied across. If one of them is null, the rules take over.\n\n## Conclusion\nNorthLens is a prototype, and a narrow one. It covers one development area, three personas, and 46 passages that I paraphrased by hand. That narrowness is why the guardrails work. Every passage has a status I checked, so the weakest-status rule has something true to stand on. I think the idea that carries over is the split. The model reads and phrases. The code decides what is allowed to be said, and a person decides what a piece of feedback means.\n\nThe weak point is freshness. Plans change, and right now a passage is only as current as the last time I edited the file. The next step is a freshness check: when a new press release or Town Planning Board paper comes in, flag the passages whose status may have moved, and have a person approve the change before residents see it. After that, voice for asking questions and not only for feedback, read-aloud answers, and a larger-text mode, because the people this is for are often the ones who find a text box hardest.\n\nIt is not an official source. Always check the latest Government release. The code is on GitHub, along with the use cases and a three-minute demo script.\n","

NorthLens

NorthLens 北覽 is a participatory-planning prototype I built for the Northern Metropolis, piloted on the Kwu Tung North New Development Area. A resident asks what the plan means for them and gets an answer where every claim is cited and tagged by how firm it is. Then they say what they think, by typing or by speaking, and a planner sees it grouped with everyone else's on a dashboard. The line I kept coming back to is that NorthLens doesn't ask AI to design Hong Kong. It uses AI to help Hong Kong design with its communities.

Project Overview

The app has two views. The resident view at / is where you pick a persona and a concern, ask a question in English or Traditional Chinese, and read the answer next to a map of the places it mentions. Below that are the Scenario Explorer and the Community Voice form. The planner view at /dashboard takes those submissions, anonymised and classified, and shows what people are worried about, who is worried, and where.

The knowledge base is small on purpose. It is 46 passages paraphrased from 23 public sources: Government press releases, Town Planning Board papers, LegCo replies, and MTR documents. Each passage carries a status. Completed, under construction, planned, proposal, under review, or superseded. That status follows the passage all the way to the screen.

It also runs with no keys at all. Without a Gemini key, retrieval falls back to keyword search and answers are composed from the retrieved passages by template. Without Supabase, feedback is written to a local JSON file. A status dot in the header shows which mode is live.

Motivation

Planning documents are public, but they are not readable. The answer to "can my mother get to the new station" is spread across an Outline Development Plan, a railway press release, and a LegCo reply, and some of those contradict each other because plans change. Kwu Tung North is a good example. The hospital that was originally planned there was superseded by a proposal in Ngau Tam Mei, and the site that was reserved is under review.

That is exactly where an ordinary chatbot is dangerous. It will repeat the old plan in a confident voice. So the rule for the build was that the model may only speak from passages it was handed, and a proposal must never read like a commitment.

The other half is the planner's side. A consultation produces hundreds of free-text submissions and somebody has to read them. I wanted the AI to do the sorting and a person to do the deciding. The AI proposes a category. A reviewer confirms it or corrects it. The original text is always kept.

Features

• Ask the plan
\nPick one of three personas, a university student, a working adult, or a caregiver of an elderly parent, then pick a concern. The answer comes back in three parts: what may change, why it matters for you, and what is uncertain. Every claim has numbered citations and a status chip, so "Under construction" and "Proposal · may change" sit side by side in the same answer.\n $\"Ask$

• Plan map
\nThe map highlights the stations, facilities, and routes that the answer cites. It uses the HKSAR Lands Department basemap, and the labels switch language with the rest of the app. The Northern Link is drawn as a dashed line because it is not built yet.\n $\"Plan$

• Scenario Explorer
\nA "living here" view that lines up everyday needs, transport, healthcare, elderly care, education, employment, green space, and cross-border access, against what the plans actually say. Each row links to its passages and shows their status. Healthcare is the row worth reading, because that is where the superseded hospital plan shows up.\n $\"Scenario$

• Community Voice
\nTick the priorities that matter, then type or press Speak. Voice works in Cantonese, in English, and in a mix of both, so "天橋一定要有 lift" comes out the way it was said. Gemini transcribes the recording into the text box and the resident checks it before submitting. The audio is never stored. Names, phone numbers, HKID numbers, emails, and flat addresses are redacted before anything is classified or saved.\n $\"Community$

• Planner dashboard
\nFilters for period, group, area, and live versus demo data. Above the fold are the headline numbers: concern rate, share from vulnerable groups, review coverage, how often reviewers agree with the AI's category, and voice share. An emerging concern banner names the issue and group with the most recent worry. Below that is a priority issues table with volume, sentiment, a 6-week trend, the 14-day change, and whether the related plan items are still open to change.\n $\"Planner$

• Issue drill-down, heatmap, and hotspots
\nOpening an issue shows suggested actions, the affected groups and areas, the related plan items with their sources, and quotes. A heatmap shows which groups worry about which issues, and a second map shows where the feedback clusters.\n $\"Heatmap\"$

• AI briefing
\nOne button writes a short briefing for the planner: a headline, up to three findings, and up to three follow-ups. It is written from the computed statistics and nothing else.\n $\"AI$

• Human review queue
\nEach submission shows the AI's proposed theme beside the original text. A reviewer confirms it or picks another from a dropdown. Reviewed rows are marked, and the original text is never changed.\n $\"Review$

• Exports
\nA consultation report and a feedback report, each with a print layout and a CSV download. Exports only ever contain responses a person has confirmed in the review queue. If nothing in the current filter has been confirmed, the buttons are disabled.\n $\"Consultation$

• Traditional Chinese and guided tours
\nThe 繁 toggle switches the whole flow, including the answers, the map labels, and the dashboard. Both views have a step-by-step tour that points at each section in turn.\n $\"Traditional$

Technical Architecture

Frontend

Next.js 16 App Router with React 19 and TypeScript
Tailwind CSS v4
Leaflet through react-leaflet, with the Lands Department basemap from the GeoData Store, which needs no API key

Retrieval

Each passage is embedded as one document holding both its English and its Chinese text, so a question in either language can find it
Three modes, in order: pgvector in Supabase through a match_kb_chunks RPC, in-memory Gemini embeddings, and keyword search
The keyword scorer is BM25-style, with stemming for English and bigrams for Chinese, plus a small synonym table so that 輪椅 or "difficulty walking" reaches the footbridge passages
The final ranking is hybrid: 60% semantic, 25% keyword, and 15% for topics that match the chosen persona and concern
A question that asks about uncertainty gives a small boost to passages that are proposed, under review, or superseded

Answering and guardrails

Gemini returns JSON against a response schema: a summary, three lists of claims, and an insufficient-evidence flag
Citations to passages that were not retrieved are dropped
A claim is dropped if it contains a number that does not appear in the passages it cites
A claim's status is the weakest status among its sources
If nothing survives, the answer says the evidence is thin and stops there

Feedback pipeline

PII redaction by pattern, before classification and before storage
Gemini classifies each submission into zone, theme, stakeholder, sentiment, and a suggested issue, with every field constrained to an enum
The result is validated again on the server. If a field is missing or outside the enum, the rule-based classifier is used instead
An empty feedback table seeds itself with 50 synthetic responses, flagged as synthetic in the data and in the UI

Insights

All dashboard statistics are computed in plain TypeScript in lib/insights.ts. No model is involved
The priority score is concerned responses × (1 + half the share from vulnerable groups) × a trend factor between 0.75 and 1.25 taken from the 14-day change

Storage

Supabase Postgres with RLS on and no public policies. The keys are server-only
Without Supabase, .data/feedback.json, written through a promise queue and a temp-file rename

Challenges and Solutions

Keeping a proposal from sounding like a promise was the main design problem. A prompt that says "be careful about uncertain plans" is a suggestion, and models ignore suggestions. So the status is not something the model writes. It comes from the passages. After the model answers, the server looks up every passage a claim cites and gives the claim the weakest status of the group. If a sentence leans on one station that is under construction and one footbridge that is only proposed, the chip says proposal. The model can phrase it however it likes. It cannot upgrade it.

Numbers were the other leak. Dates and distances are what residents will plan around, and they are what a model rounds or misremembers. Every number in a claim is pulled out and compared with the numbers in the cited passages, in both languages. One number that is not there and the whole claim is dropped. The AI briefing on the dashboard uses the same check. The server writes a block of facts from the computed statistics, the model writes prose from it, and any finding with a number that is not in that block is removed before the planner sees it. It is a blunt rule and it throws away some good sentences. I would rather lose a sentence than show a figure nobody can trace.

The model invents speech when given silence. Send a transcription model a recording of nothing and it does not return nothing. It returns a plausible sentence. For a tool that collects public opinion, that is a resident saying something they never said. There are three guards. The browser watches the microphone level while recording and counts the frames that actually contain sound, and a recording with too few never leaves the device. The server rejects clips that are too small to be real. And the response schema has a speech boolean, so the model has a way to say "nobody spoke" that is not an empty transcript. The transcript lands in the text box for the resident to check, never straight into the database.

Working with no keys shaped more of the code than I expected. Every AI step needed a second path that was not embarrassing. Retrieval has the keyword scorer. Chinese has no spaces, so the tokenizer splits runs of characters into bigrams, and a stop list removes the bigrams that turn up in every planning question. Answers have a template composer that only uses the first sentence of each retrieved passage, and its output goes through the same citation check as Gemini's. Classification has rules. The voice button and the briefing are simply hidden, because those have no honest fallback.

The local file store was easy to break. Two submissions arriving together could both read the file, both append, and one would overwrite the other. Writes now go through a single promise queue, and each write goes to a temp file that is renamed over the real one. A corrupt file is left alone and the request fails, because overwriting it with an empty list would quietly delete real feedback. There is a test for each of these: fifteen concurrent writes must all survive, a broken file must come out byte-for-byte the same, and an invalid review request must not touch the file at all.

Model output is input, and it gets validated like input. The classifier test feeds in a response with two extra properties, a replacement text and a replacement id, and checks that neither reaches the stored record. Only the six expected fields are copied across. If one of them is null, the rules take over.

Conclusion

NorthLens is a prototype, and a narrow one. It covers one development area, three personas, and 46 passages that I paraphrased by hand. That narrowness is why the guardrails work. Every passage has a status I checked, so the weakest-status rule has something true to stand on. I think the idea that carries over is the split. The model reads and phrases. The code decides what is allowed to be said, and a person decides what a piece of feedback means.

The weak point is freshness. Plans change, and right now a passage is only as current as the last time I edited the file. The next step is a freshness check: when a new press release or Town Planning Board paper comes in, flag the passages whose status may have moved, and have a person approve the change before residents see it. After that, voice for asking questions and not only for feedback, read-aloud answers, and a larger-text mode, because the people this is for are often the ones who find a text box hardest.

It is not an official source. Always check the latest Government release. The code is on GitHub, along with the use cases and a three-minute demo script.

\n",{"_10":106,"_12":107,"_40":108,"_42":109,"_50":152,"_54":102,"_14":113,"_57":58,"_26":-7,"_30":153,"_32":154},{},"# Workout Tracker\nA mobile-friendly web‑app that tracks workouts and keeps records.\n\n## Project Overview\nWorkout Tracker is a simple and focused hobby project I built in June 2023 to make logging sets painless on my phone. It’s fully client-side and fast, so I can open it at the gym, tap a few big buttons, and get back to lifting. Built with Svelte and JavaScript.\n\n## Motivation\nMost workout apps felt heavy or slow for simple strength sessions. I wanted a dead-simple way to record reps and weights without sign‑ups, ads, or a dozen screens. The goal was building something with more structure than a notes app, while keeping it simple and intuitive to use with only key features. Having frictionless logging: big controls, one screen per workout, and instant save to history.\n\n## Current Features\n• **PWA (Installable and Offline)**
\nInstall to the home screen and use it without a network connection. The app shell is cached for fast loads, and all records persist locally.\n\n• **Dashboard**
\nA clean landing with a bold title, a motivational quote, and a list of workouts shown as large, tappable cards (e.g., Bench Press, Pull Ups). An “Add Workout” button lets you create a new workout entry.\n![Dashboard](workout-1.webp \"width=350\")\n\n• **Workout Detail Layout**
\nEach workout has a top navigation bar (back button + workout name) and three tabs: Record, History, and Settings.\n![details](workout-2.webp \"width=350\")\n\n• **Record Tab**
\nReps selector and Weight (kg) selector with left/right arrows for quick changes. An “Add Set” button appends the current reps × weight to this session. A “Completed Sets” list shows sets in order, and “Record Workout” saves the whole session to history.\n\n• **History Tab**
\nA read‑only list of all sets saved for that date. Data is persisted in localStorage per workout.\n![history](workout-3.webp \"width=350\")\n\n• **Settings Tab**
\nDestructive actions scoped to the current workout: “Delete Records” clears logged sets/history; “Delete Workout” removes the workout from the app.\n![settings](workout-4.webp \"width=350\")\n\n• **Mobile‑first UX**
\nLarge, thumb‑friendly controls, consistent card and button styling, and clear hierarchy. Back navigation always returns to the dashboard.\n\n## Technical Architecture\n### Frontend (Svelte + JavaScript)\n- Svelte components for a small, reactive UI without much overhead\n- Tailwindcss and Hyper UI for a minimalistic design\n\n### Storage and Data\n- localStorage for persistence (no backend) so it works offline\n- Simple data model per workout:\n - Workout: name, id\n - Sessions keyed by date (YYYY‑MM‑DD)\n - Sets: array of { reps, weightKg } in order of entry\n- Guardrails for destructive actions (confirmations) to avoid accidental wipes\n\n## Challenges and Solutions\n### Keep it fast on mobile\nBig tap targets and minimal re-renders were important. Svelte’s reactivity made it straightforward to update only what changed while keeping the interface snappy.\n### Date handling\nDifferent phones format dates differently. I normalized the storage key to ISO‑like strings (YYYY‑MM‑DD), then formatted for display so the History tab is reliable across time zones and locales.\n## Lessons Learned and Future Enhancements\n### Less friction = more consistent logging\nBig controls and fewer steps made me log every set, not just the last one. I understand now that micro‑interactions matter more than fancy features.\n### Possible future improvements\n- Stats and charts (PRs, volume per day/week)\n- CSV export and import for backups\n- Unit toggles (lb/kg) and custom increments\n- Cloud sync as an optional add‑on if I ever need multi‑device\n## Conclusion\nWorkout Tracker is a tiny, focused tool that does exactly what I need: record sets quickly and keep them organized by date. Building it with Svelte kept it lightweight and easy to maintain, and storing data in localStorage means it’s fast and works anywhere. If you’re curious, check out the live demo or the GitHub repo—let me know what you think!","

Workout Tracker

A mobile-friendly web‑app that tracks workouts and keeps records.

Project Overview

Workout Tracker is a simple and focused hobby project I built in June 2023 to make logging sets painless on my phone. It’s fully client-side and fast, so I can open it at the gym, tap a few big buttons, and get back to lifting. Built with Svelte and JavaScript.

Motivation

Most workout apps felt heavy or slow for simple strength sessions. I wanted a dead-simple way to record reps and weights without sign‑ups, ads, or a dozen screens. The goal was building something with more structure than a notes app, while keeping it simple and intuitive to use with only key features. Having frictionless logging: big controls, one screen per workout, and instant save to history.

Current Features

• PWA (Installable and Offline)
\nInstall to the home screen and use it without a network connection. The app shell is cached for fast loads, and all records persist locally.

• Dashboard
\nA clean landing with a bold title, a motivational quote, and a list of workouts shown as large, tappable cards (e.g., Bench Press, Pull Ups). An “Add Workout” button lets you create a new workout entry.\n $\"Dashboard\"$

• Workout Detail Layout
\nEach workout has a top navigation bar (back button + workout name) and three tabs: Record, History, and Settings.\n $\"details\"$

• Record Tab
\nReps selector and Weight (kg) selector with left/right arrows for quick changes. An “Add Set” button appends the current reps × weight to this session. A “Completed Sets” list shows sets in order, and “Record Workout” saves the whole session to history.

• History Tab
\nA read‑only list of all sets saved for that date. Data is persisted in localStorage per workout.\n $\"history\"$

• Settings Tab
\nDestructive actions scoped to the current workout: “Delete Records” clears logged sets/history; “Delete Workout” removes the workout from the app.\n $\"settings\"$

• Mobile‑first UX
\nLarge, thumb‑friendly controls, consistent card and button styling, and clear hierarchy. Back navigation always returns to the dashboard.

Technical Architecture

Frontend (Svelte + JavaScript)

Svelte components for a small, reactive UI without much overhead
Tailwindcss and Hyper UI for a minimalistic design

Storage and Data

localStorage for persistence (no backend) so it works offline
Simple data model per workout:
- Workout: name, id
- Sessions keyed by date (YYYY‑MM‑DD)
- Sets: array of { reps, weightKg } in order of entry
\n
Guardrails for destructive actions (confirmations) to avoid accidental wipes

Challenges and Solutions

Keep it fast on mobile

Big tap targets and minimal re-renders were important. Svelte’s reactivity made it straightforward to update only what changed while keeping the interface snappy.

Date handling

Different phones format dates differently. I normalized the storage key to ISO‑like strings (YYYY‑MM‑DD), then formatted for display so the History tab is reliable across time zones and locales.

Lessons Learned and Future Enhancements

Less friction = more consistent logging

Big controls and fewer steps made me log every set, not just the last one. I understand now that micro‑interactions matter more than fancy features.

Possible future improvements

Stats and charts (PRs, volume per day/week)
CSV export and import for backups
Unit toggles (lb/kg) and custom increments
Cloud sync as an optional add‑on if I ever need multi‑device

Conclusion

Workout Tracker is a tiny, focused tool that does exactly what I need: record sets quickly and keep them organized by date. Building it with Svelte kept it lightweight and easy to maintain, and storing data in localStorage means it’s fast and works anywhere. If you’re curious, check out the live demo or the GitHub repo—let me know what you think!

\n",{"_10":115,"_12":116,"_40":117,"_42":118,"_50":121,"_54":102,"_14":124,"_57":58,"_26":-7,"_30":156,"_32":157},"\n# Vocab Exercise Generator\nA simple web‑app that generates fill‑in‑the‑blank sentence exercises from dictionary example sentences, designed for English learners who need more support.\n\n## Project Overview\nVocab Exercise Generator is a lightweight tool I finished in July 2022. You paste a list of target words, press Generate, and the app outputs a numbered set of sentences with the target word blanked out. You can download the worksheet as a text file, a Word (.docx) file, or a PDF. It’s fast, ad‑free, and built to help teachers and students create practice materials in seconds.\n\n## Motivation\nWhen I was tutoring weaker classmates, I spent a lot of time writing simple “fill‑in” sheets by hand as they help with active retrieval. I noticed that real dictionary examples are clearer than sentences I make up, especially for verbs with tricky usage. This app automates that process: grab authentic examples, blank the target word, and package everything neatly for printing or sharing.\n\n## Current Features\n• **Word List to Worksheet**
\nEnter vocabulary words (one per line), click Generate, and get a clean, numbered exercise list with an answer key.\n![screenshot1](vocab-1.webp \"width=500\")\n![screenshot2](vocab-2.webp \"width=500\")\n\n• **Example‑Based Sentences**
\nSentences are sourced from reputable dictionaries and lightly cleaned for readability before the target word is blanked out.\n\n• **Download Options**
\nExport your exercise as Text (.txt), Word (.docx), or PDF (.pdf) with a single click.\n![screenshot3](vocab-3.webp \"width=500\")\n\n• **Responsive, Minimal UI**
\nA simple, distraction‑free interface that works on both desktop and mobile.\n## Technical Architecture\n### Backend (Python)\n- FastAPI: exposes API endpoints for generating exercises and returning downloadable files\n- BeautifulSoup4: scrapes dictionary pages and extracts example sentences\n### Frontend (Svelte + JavaScript)\n- Svelte: drives a reactive UI for the word list, generated content, and downloads\n- Simple state management: keeps input, generated sentences, and answer keys in sync\n- Download helpers: triggers server exports for .txt, .docx, and .pdf\n\n## Challenges and Solutions\n### Unpredictable dictionary markup\nDictionary pages structure examples differently and change their HTML over time. Parsing them reliably was harder than I expected.\n\nI wrote focused scrapers for example blocks and added fallbacks when a page layout didn’t match. Lightweight cleaning removes citation clutter, odd punctuation, and trailing ellipses.\n### Export formatting\nGetting numbering and line breaks to look good across .txt, .docx, and .pdf is surprisingly fiddly.\n\nThe pdf option still remains buggy today. If the sentence is too long, it will just overflow out of the page.\n## Conclusion\nThis project started as a tiny helper for quick worksheets and turned into a handy, one‑click generator that saves time for teachers and learners. It’s simple, fast, and does one job well: turn your word list into authentic, fill‑in‑the‑blank practice with an answer key. If you want to try it, check out the live demo and the code—feedback welcome!","

Vocab Exercise Generator

A simple web‑app that generates fill‑in‑the‑blank sentence exercises from dictionary example sentences, designed for English learners who need more support.

Project Overview

Vocab Exercise Generator is a lightweight tool I finished in July 2022. You paste a list of target words, press Generate, and the app outputs a numbered set of sentences with the target word blanked out. You can download the worksheet as a text file, a Word (.docx) file, or a PDF. It’s fast, ad‑free, and built to help teachers and students create practice materials in seconds.

Motivation

When I was tutoring weaker classmates, I spent a lot of time writing simple “fill‑in” sheets by hand as they help with active retrieval. I noticed that real dictionary examples are clearer than sentences I make up, especially for verbs with tricky usage. This app automates that process: grab authentic examples, blank the target word, and package everything neatly for printing or sharing.

Current Features

• Word List to Worksheet
\nEnter vocabulary words (one per line), click Generate, and get a clean, numbered exercise list with an answer key.\n $\"screenshot1\"$ \n $\"screenshot2\"$

• Example‑Based Sentences
\nSentences are sourced from reputable dictionaries and lightly cleaned for readability before the target word is blanked out.

• Download Options
\nExport your exercise as Text (.txt), Word (.docx), or PDF (.pdf) with a single click.\n $\"screenshot3\"$

• Responsive, Minimal UI
\nA simple, distraction‑free interface that works on both desktop and mobile.

Technical Architecture

Backend (Python)

FastAPI: exposes API endpoints for generating exercises and returning downloadable files
BeautifulSoup4: scrapes dictionary pages and extracts example sentences

Frontend (Svelte + JavaScript)

Svelte: drives a reactive UI for the word list, generated content, and downloads
Simple state management: keeps input, generated sentences, and answer keys in sync
Download helpers: triggers server exports for .txt, .docx, and .pdf

Challenges and Solutions

Unpredictable dictionary markup

Dictionary pages structure examples differently and change their HTML over time. Parsing them reliably was harder than I expected.

I wrote focused scrapers for example blocks and added fallbacks when a page layout didn’t match. Lightweight cleaning removes citation clutter, odd punctuation, and trailing ellipses.

Export formatting

Getting numbering and line breaks to look good across .txt, .docx, and .pdf is surprisingly fiddly.

The pdf option still remains buggy today. If the sentence is too long, it will just overflow out of the page.

Conclusion

This project started as a tiny helper for quick worksheets and turned into a handy, one‑click generator that saves time for teachers and learners. It’s simple, fast, and does one job well: turn your word list into authentic, fill‑in‑the‑blank practice with an answer key. If you want to try it, check out the live demo and the code—feedback welcome!

\n",{"_10":126,"_12":127,"_40":128,"_42":129,"_50":131,"_54":102,"_14":134,"_57":58,"_26":-7,"_30":159,"_32":160},"# The Dictionary Hub\n\nAn online dictionary that compiles results from different popular dictionaries to one place. Designed for convenience among students.\n\n## Project Overview\n\nThe Dictionary Hub is one of my earliest \"useful\" project. Completed on June 2022. It was built with Python FastAPI as its backend and JavaScript React as its frontend.\n\n## Motivation\nThis project aims to provide a place for students to look up definitions of words quickly. When I was learning English, I often found myself not understanding the definition of a word in a dictionary, and searching the word in a different one. This gave me the idea of this website, which compiles definitions from different dictionaries. Hoping to help my fellow students.\n\n## Current Features (Implemented)\n\n• **Word Search Functionality**
\nUsers can enter a word via a simple search bar, and the application queries definitions from multiple sources (e.g., Cambridge, Oxford, and Merriam-Webster) using web scraping techniques.\n\n• **Multi-Source Definitions Compilation**
\nThe app aggregates and displays definitions, pronunciations, and examples from various dictionaries in a single, unified interface, making it easier for users to compare results without switching sites.\n\n• **Synonyms and Antonyms Display**
\nIn addition to definitions, the application provides synonyms and antonyms for searched words, to enhance vocabulary building and offer a more complete linguistic resource.\n\n• **Word of the Day Feature**
\nUpon a user's launch of the site, it automatically displays definitions, pronunciations, and related information for Merriam-Webster's \"word of the day,\" encouraging daily vocabulary building and engagement.\n\n• **Chrome Extension Integration**
\nA dedicated Chrome extension that allows users to select text on any webpage and perform a quick search directly through The Dictionary Hub, providing on-the-fly lookups for enhanced convenience.\n\n• **Responsive Design for Mobile and Desktop**
\nThe application is optimized for various screen sizes, offering a fluid and adaptable layout that works intuitively on both mobile devices and desktops.\n\n• **Light and Dark Themes**
\nUsers can switch between light and dark modes to personalize their experience.\n\n## Technical Architecture\n\n### Backend (Python)\n- FastAPI: to provide api endpoints\n- BeautifulSoup: to scrape the information out of different online dictionaries\n\n### Frontend (TypeScript + React)\n- TypeScript: for static type checking and code organization\n- React: for building the user interface\n- Chakra UI: for providing a modern, responsive design system\n\n## Challenges and Solutions\n### Complex dictionary landscape\nWhen I was building this, web scraping was a big headache because these dictionary sites have very complex layouts and it's vastly different from scraping other data. With the nature of a dictionary, there can be multiple interpretation of a word with different meanings, part of speech and examples. It's very hard scrape them in an orderly way. \n\nAt the end, I successfully wrote scripts to scrape them. But it comes at a cost of messy code and nearly impossible maintenance.\n\n### Strict dictionary security\nInitially, for the \"Synonyms and Antonyms\" feature, I tried scraping the thesaurus.com website. After some exploring, I found that the frontend of the thesaurus.com website exposes its API endpoint for fetching the synonyms and antonyms from its database. I took advantage of that and called its API directly in my backend, to avoid the hassle of some complex scraping script.\n\nAnd 2 years later, I think they found out and removed the API. To ensure the feature still works, I used the datamuse API for getting synonyms and antonyms. This way is more reliable and consistent as if I built another script, they may change the layout and my feature will be unusable again.\n\n### CI/CD pipeline\nAlthough this is a small project and it probably doesn't require a CI/CD pipeline, I still implemented one just for the fun of it. I used \"cloud build\" to automatically build the docker image of the backend whenever the master branch of the GitHub repository have a new commit. After successfully building the image it will be deployed on \"cloud run\". Setting up the google cloud platform is a pain. I had to read A LOT of documentation and set a lot permissions. I took me 1 whole day to get it working.\n \n\n## Lessons Learned and Future Enhancements\nBeing one of the first project I wrote. I learned a lot.\n\n### Why clean code is important\nAfter 3 years, I read the web scraping code and it is pretty much uninterpretable. The code I wrote was messy and has little comments which doesn't explain the code. Modifying the code is impossible even for myself. The website is still working but if it breaks, fixing it will require massive amount of work and time.\n\nI understanding now maintaining a project is as important as building it. Writing clean code and documentation is absolutely crucial for myself and other coder who might maintain it.\n\n### You should read the docs first\nAs a beginner in web development, web-scraping and cloud services. I had to learn and figure out a lot of new stuff. I spent most of my time searching for ways to accomplish my development goals.\n\nTurns out a lot of things I want to do is already shown in the docs as an example. If only I had read the docs earlier, I wouldn't have wasted that much time trying to figure out the methods and settings.\n\n## Conclusion\nWrapping this up, The Dictionary Hub was one of my first real projects that actually felt useful, and I'm pretty proud of how it turned out back in 2022. It's basically a one-stop spot for looking up words from places like Cambridge, Oxford, and Merriam-Webster, all without ads or jumping between sites—super handy for students who were struggling with English vocab. Sure, dealing with web scraping got messy, and I learned the hard way that clean code and docs are a must if you want to fix stuff later without pulling your hair out. But hey, it taught me tons about FastAPI, React, BeautifulSoup, and even setting up a CI/CD pipeline on Google Cloud (which was a total pain but fun to figure out). For the future, I'd love build a prettier interface or maybe some AI-generated examples. If you're curious, go check out the live demo or the GitHub repo—let me know what you think!\n","

The Dictionary Hub

An online dictionary that compiles results from different popular dictionaries to one place. Designed for convenience among students.

Project Overview

The Dictionary Hub is one of my earliest "useful" project. Completed on June 2022. It was built with Python FastAPI as its backend and JavaScript React as its frontend.

Motivation

This project aims to provide a place for students to look up definitions of words quickly. When I was learning English, I often found myself not understanding the definition of a word in a dictionary, and searching the word in a different one. This gave me the idea of this website, which compiles definitions from different dictionaries. Hoping to help my fellow students.

Current Features (Implemented)

• Word Search Functionality
\nUsers can enter a word via a simple search bar, and the application queries definitions from multiple sources (e.g., Cambridge, Oxford, and Merriam-Webster) using web scraping techniques.

• Multi-Source Definitions Compilation
\nThe app aggregates and displays definitions, pronunciations, and examples from various dictionaries in a single, unified interface, making it easier for users to compare results without switching sites.

• Synonyms and Antonyms Display
\nIn addition to definitions, the application provides synonyms and antonyms for searched words, to enhance vocabulary building and offer a more complete linguistic resource.

• Word of the Day Feature
\nUpon a user's launch of the site, it automatically displays definitions, pronunciations, and related information for Merriam-Webster's "word of the day," encouraging daily vocabulary building and engagement.

• Chrome Extension Integration
\nA dedicated Chrome extension that allows users to select text on any webpage and perform a quick search directly through The Dictionary Hub, providing on-the-fly lookups for enhanced convenience.

• Responsive Design for Mobile and Desktop
\nThe application is optimized for various screen sizes, offering a fluid and adaptable layout that works intuitively on both mobile devices and desktops.

• Light and Dark Themes
\nUsers can switch between light and dark modes to personalize their experience.

Technical Architecture

Backend (Python)

FastAPI: to provide api endpoints
BeautifulSoup: to scrape the information out of different online dictionaries

Frontend (TypeScript + React)

TypeScript: for static type checking and code organization
React: for building the user interface
Chakra UI: for providing a modern, responsive design system

Challenges and Solutions

Complex dictionary landscape

When I was building this, web scraping was a big headache because these dictionary sites have very complex layouts and it's vastly different from scraping other data. With the nature of a dictionary, there can be multiple interpretation of a word with different meanings, part of speech and examples. It's very hard scrape them in an orderly way.

At the end, I successfully wrote scripts to scrape them. But it comes at a cost of messy code and nearly impossible maintenance.

Strict dictionary security

Initially, for the "Synonyms and Antonyms" feature, I tried scraping the thesaurus.com website. After some exploring, I found that the frontend of the thesaurus.com website exposes its API endpoint for fetching the synonyms and antonyms from its database. I took advantage of that and called its API directly in my backend, to avoid the hassle of some complex scraping script.

And 2 years later, I think they found out and removed the API. To ensure the feature still works, I used the datamuse API for getting synonyms and antonyms. This way is more reliable and consistent as if I built another script, they may change the layout and my feature will be unusable again.

CI/CD pipeline

Although this is a small project and it probably doesn't require a CI/CD pipeline, I still implemented one just for the fun of it. I used "cloud build" to automatically build the docker image of the backend whenever the master branch of the GitHub repository have a new commit. After successfully building the image it will be deployed on "cloud run". Setting up the google cloud platform is a pain. I had to read A LOT of documentation and set a lot permissions. I took me 1 whole day to get it working.

Lessons Learned and Future Enhancements

Being one of the first project I wrote. I learned a lot.

Why clean code is important

After 3 years, I read the web scraping code and it is pretty much uninterpretable. The code I wrote was messy and has little comments which doesn't explain the code. Modifying the code is impossible even for myself. The website is still working but if it breaks, fixing it will require massive amount of work and time.

I understanding now maintaining a project is as important as building it. Writing clean code and documentation is absolutely crucial for myself and other coder who might maintain it.

You should read the docs first

As a beginner in web development, web-scraping and cloud services. I had to learn and figure out a lot of new stuff. I spent most of my time searching for ways to accomplish my development goals.

Turns out a lot of things I want to do is already shown in the docs as an example. If only I had read the docs earlier, I wouldn't have wasted that much time trying to figure out the methods and settings.

Conclusion

Wrapping this up, The Dictionary Hub was one of my first real projects that actually felt useful, and I'm pretty proud of how it turned out back in 2022. It's basically a one-stop spot for looking up words from places like Cambridge, Oxford, and Merriam-Webster, all without ads or jumping between sites—super handy for students who were struggling with English vocab. Sure, dealing with web scraping got messy, and I learned the hard way that clean code and docs are a must if you want to fix stuff later without pulling your hair out. But hey, it taught me tons about FastAPI, React, BeautifulSoup, and even setting up a CI/CD pipeline on Google Cloud (which was a total pain but fun to figure out). For the future, I'd love build a prettier interface or maybe some AI-generated examples. If you're curious, go check out the live demo or the GitHub repo—let me know what you think!

\n","actionData","errors"]

Blog

Running Local AI on a 16GB MacBook Air