Explainer · dgem

dgem

Templates, one-pass readout, honest uncertainty and routing for a zero-shot decision engine on DiffusionGemma.

dgem takes some text or an image (the state) and a list of typed questions from a template file. For each question it returns the answer it picked, a probability for every allowed answer, and a hesitation score. All questions are answered together in one forward pass. We don't change the model weights. Confident answers are used directly; hesitant ones go to a person or to Gemini.

This page explains what you can build, how a decision is read, what the confidence numbers mean and what we learned testing ways to correct them. The documentation starts at the docs home.

Base: DiffusionGemma 26B-A4B (frozen weights) Serving: Vertex AI, Cloud Run GPU or Apple Silicon Decision Studio: dgem serve → localhost:8090
01

What you can build

Behaviour lives in a template file (.json.tmpl) in git. Adding a question or an option is an edit, not a training job.

02

How an answer is made

Template
Typed questions: boolean, choice (≤26 options), score
→
Canvas
Each question gets a masked answer slot; options become letters A–Z
→
One forward pass
All slots are filled together and can see each other
→
Answer
Chosen option, probability of every option, hesitation

Questions that depend on another answer (depends_on) run in a second pass; questions with more than 26 options use a two-stage bracket.

Unlike a chat model, nothing is written word by word, so there is no JSON to parse and the probabilities belong to the decision itself rather than to formatting tokens.

03

Confidence

Hesitation is the entropy of an answer's probabilities, scaled to 0–100% by the number of options: 0% when one answer has all the probability, 100% for a coin toss. It makes a yes/no question and a 26-option question comparable.

HesitationMeaningWhat to do
< 16%ClearAct automatically
16–50%Somewhat unsureEscalate if errors are costly
> 50%Very unsureSend to a person or to Gemini

In our tests hesitation alone flags most wrong answers. Calibration is still policy- and data-specific: check your own with Calibrate your policy, and read Confidence beyond Shannon for how hesitation-gating works.

04

What we learned trying to correct the probabilities

DiffusionGemma, like other language models, favours the first option when it is unsure. We tested ways to fix that at request time; dgem now gates on hesitation and monitors option order on every release instead:

TechniqueFindingStatus
Null-prior de-biasing ("tare the scale")Helped some suites and hurt othersResearch; validate per suite
Reversed "mirror" ballot on the same canvasLost accuracy because both slots used letters A, B, C for different options; digit labels fix that but add littleResearch
Mirror in a separate passA small extra signal, no better than reading twice, for double the costResearch
Temperature scaling (held-out, per policy)Improves calibration when fitted on the policy's own data; the best value differs by domainRecommended per policy
Hesitation gate + Gemini cascadeRecovers most of the larger model's accuracy while escalating a minority of itemsRecommended
Two lessons for template authors
Question ids are read by the model: a second slot named …mirror… changed answers. Use neutral, descriptive ids. And don't give two slots the same letters for different meanings.
05

Serving

A gateway (dgem serve) routes to Vertex first and falls back to Cloud Run. The same image, templates, CLI, HTTP API and MCP server work on a laptop, Cloud Run and Vertex. /health reports the serving version. Measure latency on your own deployment: Latency and capacity.

06

Limits

07

Try it

make build
./bin/dgem decide -t templates/support_triage.json.tmpl \
  -v 'ticket=Charged twice for the annual plan' --stats
# or connect an MCP client to your own gateway:
./bin/dgem mcp --remote https://<your-dgem-gateway>/mcp

Tutorial: Your first decision policy. Deploying your own: From laptop to production. Changes: CHANGELOG.