HanashiGemma (話Gemma): a patient Japanese conversation partner that runs on my friend's laptop

adricasi — Sun, 04 Oct 2026 20:36:33 +0000

This is a submission for the Hacktoberfest Weekend Challenge: Build for a Friend

What I Built

My friend Marc is learning Japanese for a trip to Japan next year. He has been studying with real dedication, and like many learners, they find that the jump from textbook to a live conversation is the hardest part: real replies come quickly, there's little time to think about which particle fits, and it's hard to find a relaxed place to practise where small mistakes don't matter.

I wanted to give them exactly that: a calm, patient partner they can practise with whenever they like, at their own pace.

So I built HanashiGemma (hanashi 話 = "talk"): a patient roleplay partner for real situations. You pick a scene: buying a train ticket at Shinjuku, ordering ramen at an izakaya, or asking for directions in Kyoto. Gemma plays the station clerk, the server or a friendly local, in beginner Japanese (JLPT N5–N4, polite form).

Every line Gemma says comes with the help a beginner needs, at their own pace:

Furigana over the kanji, so every word can be read.
Romaji and English one click away (hidden by default, so you try to read first).
Gemma's Breakdown: the particles and phrases in that line, explained in English.
Suggested replies: if you freeze, click one, edit it, send it.
Gentle Fix: if your sentence is off, a friendly card shows what you wrote, a more natural version and why, and the scene just continues. No red marks, never the word "wrong".

Demo

HanashiGemma DEMO

In the video, everything runs locally on my laptop with Ollama, with no internet. I order ramen at an izakaya: first in English (Gemma shows おすすめは何ですか？, "What do you recommend?"), then in romaji (ビールもお願いします。, "A beer too, please."), then in Japanese (おかいけいをおねがいします。, "The bill, please."), and finally with a real mistake: カードがはらえますか？ → Gentle Fix カードで払えますか？ ("Can I pay by card?";
で means "by/with").

Code

How I Built It

The open pieces it runs on

Gemma 4: the open-weight model at the core. The demo runs gemma4:12b locally; on a smaller laptop, gemma4:e4b works too. gemma4:12b follows longer conversations better, and switching between them is a single setting.

src/prompt.ts builds the system prompt. It sets the scenario role, keeps Japanese at N5–N4 with desu/masu, and defines the Gentle Fix rules (including English or romaji input and no writing-system corrections). It also asks for the JSON reply shape.
src/scenarios.ts defines the 3 fixed scenarios that the prompt plugs in.
src/reply.ts holds the zod schema and the cross-checks. Segments must join back to jp, kanji need readings, and breakdown phrases must appear in jp.
src/server/turn.ts runs the call, validates the reply and retries once, then shows a friendly error (REQ-003).
src/model/ has the adapters (ollama.ts, gemini.ts, factory.ts), chosen by GEMMA_BACKEND.

Ollama: local inference. It runs Gemma on the laptop itself, with no internet connection and no account, and supports structured output, which the whole app relies on.
Open-source frameworks around it: TypeScript, Node.js with Hono for a small local server, and zod to validate everything Gemma returns.

How the app is built around Gemma

Browser ▶ small local server builds the scene prompt and checks every reply ▶ Gemma 4 on Ollama (same laptop)

One structured answer per turn. Every turn, Gemma returns a single JSON object: its reply split into words with their hiragana readings (for the furigana), the romaji, an English translation, a short grammar breakdown, suggested replies and, when helpful, a Gentle Fix. Ollama receives the JSON schema, so Gemma's output always has exactly that shape, and the interface is simply a view of that object.
Trust, but verify. Small models make small mistakes, so the server checks every reply before it is shown: the words must spell the sentence exactly, grammar notes must refer to words that are really there, and readings must be in hiragana. If something is off, Gemma gets one retry with the reason, so a broken turn is never shown.

What I learned: with small open models, details matter. Making the "reading" field required in the schema took one tricky turn from failing 5 times out of 6 to working almost every time.

Architecture Decision Record

Why Does Open Innovation Matter?

For this project, an open-weight model is the whole point:

It runs on my friend's laptop with no internet. Practising on a train or a plane works the same as at home.
Their mistakes stay private. With Gemma running locally, nothing they type leaves their computer, and the app stores nothing at all. A closed API would send every hesitant sentence to someone else's server.
It costs nothing to practise. No API key, no quota, no bill. My friend can practise for hours without anyone counting tokens.
I can swap the model. Gemma 4 comes in several sizes. Picking e4b for any laptop or 12b for better conversations is one setting, and the same code runs against hosted Gemma too. Nothing ties the app to one vendor.

That's what made it something I could actually hand to a friend and say "use it as much as you want".

My Agent Session

I built it spec-first with an AI coding agent (Claude Code) as the main developer and Gemini as an independent code reviewer. The cross-review caught several real bugs before release.

Prize Categories

Best Use of Gemma

@adricasi - Adrià Casals.

DEV Community: adricasi