Kyūmei: Why I Taught a Local Gemma Model to Refuse to Guess on Hardware Faults

Swetabh Tripathy — Sun, 04 Oct 2026 22:14:51 +0000

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

Kyūmei: A Local Gemma 4 Agent That Cites Evidence Before Naming a Cause

TL;DR

What: Kyūmei turns a messy hardware complaint, or a HWiNFO64 sensor log, into numbered evidence, hypotheses that must cite that evidence, and troubleshooting steps ordered from safest to most invasive. It runs Gemma 4 E2B (or Gemma 2 9B) locally through Ollama.

The trick: Gemma reasons. Plain code validates the JSON schema, drops causes that cite evidence that doesn't exist, and forces a hard "stop and get it repaired" answer for battery swelling and burning-smell cases.

It can say no: If there are fewer than two verifiable clues, it returns needs_more_info and provides 1-click follow-up questions instead of guessing.

Results: 4/4 unit tests on the guardrails pass. On 8 benchmark test scenarios, 7 passed schema validation on the first try and 1 recovered cleanly via the automatic 1-turn retry loop.

For: Rohit, whose 3-year-old gaming laptop was screaming at idle and dying mid-game.

The 2 a.m. problem

My friend Rohit had an Asus TUF gaming laptop that was acting up during our Hacktoberfest hackathon prep:

"Bro, the bottom feels like a hot frying pan even when I'm just looking at VS Code, the fans sound like a jet taking off at idle, and after 20 minutes it just shuts off with zero warning."

He'd already spent an evening googling. He got the usual soup of generic forum advice: update your BIOS, reinstall Windows, update graphics drivers, run an antivirus scan, or the dreaded "your motherboard VRM is dead, buy a new laptop."

Nobody was completely wrong. Nobody was useful either. A laundry list of everything that can possibly go wrong isn't a diagnosis. A diagnosis says: here is what you told me, here is the exact evidence that points to this specific cause, and here is the cheapest, non-invasive check that would prove me wrong.

So I built that, and named it Kyūmei (究明) — Japanese for "to investigate the truth / thorough examination."

What it does

You describe the problem the way a real human would:

Laptop gets very hot on the bottom and fan is loud while idle, shutting down abruptly after 20 minutes of light use.

Kyūmei processes the input and returns a structured, citation-backed diagnostic report:

Evidence: Atomic facts extracted from your symptom, each with an identifier (E1, E2, E3).
Candidate Causes: Hypotheses where every single cause must cite at least one valid evidence ID.
Verification: A concrete physical or sensor check to validate or disprove each cause.
Ordered Remediation: Non-invasive checks first (software/airflow), internal disassembly last.
A refusal to guess: If you provide vague inputs like "my laptop died", it returns needs_more_info with interactive follow-up questions.

A Real Diagnostic Run

INPUT: "Laptop gets very hot on the bottom and fan is loud while idle, shutting down abruptly after 20 minutes of light use."

[E1] "Laptop gets very hot on the bottom"
[E2] "fan is loud while idle"
[E3] "shutting down abruptly after 20 minutes"

[C1] Heatsink exhaust fins clogged with compacted dust or lint blanket.
     Evidence: [E1], [E2]  |  Confidence: HIGH
     Verification: Inspect exhaust vents with a flashlight to verify lint blockage.

[C2] Degraded or dried thermal interface compound (TIM) on CPU/GPU die.
     Evidence: [E1], [E2], [E3]  |  Confidence: HIGH
     Verification: Log HWiNFO64 sensor data; check if delta temp jumps to 95°C+ within 3s.

TROUBLESHOOTING PLAN:
  1. (Low Risk)   Ensure operation on a hard, flat surface to rule out vent smothering.
  2. (Low Risk)   Blow short bursts of compressed air into exhaust vents while powered down.
  3. (Safe)       Inspect Task Manager for rogue background compute / crypto-miners.

STATUS: OK

It also reads raw telemetry: export a HWiNFO64 sensor log (.csv or .txt), drop it in, and Kyūmei automatically extracts CPU package temps, PROCHOT throttling flags, GPU hot spot temps, fan RPMs, NVMe drive wear, and battery degradation before piping them into the reasoning pipeline. The UI features four dedicated tabs: Hardware Fault Diagnostics, Telemetry Log Analyzer, Game & AI Feasibility Estimator, and Rogue Process / Miner Triage.

The idea: the model reasons, the code checks

I didn't want "user asks, LLM hallucinates, ship it." Small local models can sound confident while being subtly or dangerously wrong. In hardware diagnostics, that could mean telling someone to puncture a swollen lithium-ion pouch or replace a working motherboard.

User Symptom / HWiNFO64 Log
            │
            ▼
      FastAPI / CLI
            │
            ▼
  Gemma 4 E2B via Ollama  (guided by Agent Skill & JSON Schema)
            │
            ▼
       Raw JSON ───► JSON Schema Draft 2020-12 ──[Invalid]──► 1 Auto-Retry Loop
            │                                                       │
         [Valid] ◄──────────────────────────────────────────────────┘
            │
            ▼
    Deterministic Guardrails Engine
       ├── Grounding Filter: Drop causes citing phantom evidence IDs
       ├── Battery / Thermal Safety Clamp: Force technician escalation
       └── Remediation Ordering: Safe software checks first, teardown last
            │
            ▼
    Sanitized Diagnostic Report + Interactive Cross-Highlight UI

Gemma does what language models are best at: parsing messy, human language and identifying semantic relationships. Deterministic Python code does what code is best at: enforcing non-negotiable rules.

Evidence Grounding Invariant: If Gemma suggests a cause backed by E4 and E4 was never extracted in the evidence array, the guardrail immediately drops that cause from the output.
Physical Safety Clamp: If the symptom mentions battery swelling, a bulging trackpad, popping chassis seams, smoke, or a burning smell, the engine overrides the response status to safety_alert, sets a high-contrast hazard warning, and locks the plan to STOP USE IMMEDIATELY & REFER TO A CERTIFIED TECHNICIAN.
Ambiguity Triage: When someone gives a two-word complaint like "laptop dead", the model doesn't guess. The guardrail sets status: "needs_more_info" and generates targeted, clickable questions (e.g. "Do any charging LEDs light up when plugged in?").

The diagnostic instructions live in a standardized Agent Skill (skill/SKILL.md) and formal schema (skill/schema.json), making the skill portable to any agentic runtime.

Where the small model broke

During testing with Gemma 4 E2B and Gemma 2 9B on consumer hardware, we encountered three real failure modes:

Citation Hallucinations: On longer symptoms, the model would invent plausible causes citing non-existent IDs like ["E4", "E99"].
Schema Inconsistencies: The small model occasionally emitted evidence_ids as a single string instead of a JSON array of strings ("E1" instead of ["E1"]), or wrapped the payload in conversational markdown commentary.
Premature Certainty on Vague Prompts: When given "my screen went black", the raw model would sometimes jump straight to "replace the display panel" instead of asking whether an external monitor works.

Every failure mode became an explicit deterministic check in app/guardrails.py and app/validator.py.

Test Suite & Benchmark Metrics

Check	Result
Guardrail Unit Tests (Schema, missing fields, ungrounded cause pruning, battery safety clamp)	4 / 4 PASS (0.42s)
Benchmark Scenarios with Schema-Valid Output on 1st Try	7 / 8
Scenarios Recovered via 1-Turn Auto-Retry Loop	1 / 8
Causes Dropped for Citing Phantom / Missing Evidence	3 instances caught & pruned
Ambiguous Inputs Correctly Triaged to `needs_more_info`	100% (Scenario 04 & vague edge tests)
Hazardous / Swollen Battery Symptoms Clamped to Safety Alert	100% (Scenario 03 & thermal runaways)

Run python -m pytest tests/ and python tests/run_examples.py to reproduce.

An honest caveat: Grounding proves that every candidate cause has a verified paper trail in the evidence. It does not prove the model picked the ultimate root cause. That is why every single hypothesis includes a tangible verification step.

What Rohit said

"The fact that it highlighted the exact words from my rambling complaint and connected them to the clogged heatsink made so much sense. We blew out the exhaust with compressed air, and the idle temps dropped from 89°C to 48°C. Best part: it didn't tell me to reinstall Windows."

Why open, and why local

Hardware diagnostics often involve sensitive telemetry: serial numbers, background processes, user directories, and crash dumps. You shouldn't have to upload your device logs to a closed cloud API.

Because Gemma is open-weight and runs locally through Ollama, the entire reasoning pipeline operates 100% offline with zero data leakage. We tested this on an NVIDIA GeForce RTX 3050 Laptop GPU (6 GB VRAM) running on Windows 11 with Python 3.14 — completely offline with Wi-Fi disabled.

A note on the hosted showcase: For users without local Ollama setups, the repository includes an optional cloud hybrid mode powered by OpenRouter (google/gemma-2-9b-it). The live demo on Embarko uses this hybrid mode so anyone can test it directly from their browser, but local mode remains the first-class privacy standard.

How I built it, and how I used AI

Backend: Python 3.10+, FastAPI, Uvicorn, Pydantic v2, jsonschema (Draft 2020-12).
Inference: Ollama (gemma4:e2b, gemma2:9b, llama3.1:8b) with optional OpenRouter cloud fallback.
Frontend: Vanilla modern HTML5, CSS3 with glassmorphism and bidirectional hover cross-highlighting, and reactive ES6 JavaScript.
AI Tooling Disclosure: Built using Google Antigravity IDE (Gemini) as an AI pair programmer for scaffolding boilerplate, CSS polish, and documentation structuring. The core diagnostic reasoning axioms, Agent Skill specification, schema invariants, deterministic guardrails, HWiNFO64 parser, and test suite were designed and implemented by the human author. A full file-by-file audit is published in AI_DISCLOSURE.md.

Limitations

Kyūmei is a triage and diagnostic assistant, not a replacement for a certified repair technician.
Physical safety cases (swollen batteries, electrical burning) strictly halt automated troubleshooting.
Telemetry parsing currently targets HWiNFO64 .txt and .csv logs; screenshot OCR is planned for a future release.
Evaluated on an 8-scenario benchmark suite on consumer RTX 3050 6GB hardware.

What's next

Persistent Local Case History: Storing past diagnostic sessions locally so follow-up sensor logs track whether a repair actually fixed the thermal delta.
Screenshot / Thermal Camera OCR: Ingesting mobile photos of BIOS screens, BSOD error codes, and FLIR thermal camera captures.

Try it

Local Setup (100% Offline with Ollama)

git clone https://github.com/Tswetabh/Agent-Kyumei.git
cd Agent-Kyumei/kyumei
python -m venv .venv
.venv\Scripts\activate      # On Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
ollama pull gemma4:e2b
python -m uvicorn app.main:app --host 127.0.0.1 --port 8000

Source Code: github.com/Tswetabh/Agent-Kyumei
Live Demo (Embarko): agent-kyumei.embarko.app
Showcase Listing: embarko.ai/showcase/app/agent-kyumei
Cloud Mirror: agentkyumei.vercel.app

Prize categories

Best Use of Gemma: Gemma 4 E2B runs locally via Ollama to handle messy diagnostic natural-language reasoning, while strict deterministic Python code enforces JSON schema validation, evidence-grounding invariants, and physical safety clamping.

Built during Hacktoberfest Hack Day Indore (PyData Indore × MLH).

DEV Community: Swetabh Tripathy