dgem turns DiffusionGemma (26B-A4B-it, a discrete-diffusion Gemma 4) into a decision engine. You describe a decision as a small template of typed questions (boolean, choice, score). dgem places every question on the model's bidirectional canvas and reads a probability for every allowed answer, for every question, in one forward pass. There is no free-text generation to parse, and every answer comes with a per-question uncertainty score you can use to decide when to act automatically and when to escalate.
📖 Docs site: googlecloudplatform.github.io/dgem
| Piece | What it does | Start here |
|---|---|---|
Decision engine (dgem decide) |
Compiles .json.tmpl Policy-as-Template files into one-pass multi-question readouts with per-option probabilities and Shannon entropy. |
The Journey to Decision Models · Template Catalog |
| Hesitation-gated decisions | A probability for every option and a hesitation score from one pass; hesitant answers are handed off; calibration fitted per domain. | Confidence beyond Shannon · Confidence and calibration |
| Hesitation-gated cascade | Answers low-hesitation decisions directly and hands the rest to Vertex AI gemini-3.8-flash with dgem's probabilities attached. |
Authoring and cascades |
| Four surfaces | CLI, HTTP gateway (/api/decide, /v1/systemone), MCP server (dgem mcp, /mcp), and the embedded Decision Studio web app (dgem serve). |
Studio, MCP & API · CLI reference |
| Evaluation tools | dgem bench-* harnesses and a regression matrix (scripts/bench_matrix.py) to measure your own deployment and compare a candidate with a baseline. |
Evaluate a deployment · Regression matrix |
| Serving | Vertex AI Dedicated Endpoint on RTX PRO 6000, Cloud Run GPU (scale to zero), GCE VMs, and local Apple Silicon (Metal). | From laptop to production |
Full walkthrough: Run on your laptop.
Choose the option matching your hardware:
- Local Apple Silicon Mac (Metal) — No Docker or cloud needed:
make setup && make download && make local-up # engine on :8080, Decision Studio on :8090
- Any Linux workstation with an NVIDIA GPU (Docker) — build the serving image into your own
Artifact Registry first (Build the serving image), then:
docker run --gpus all -p 8080:8080 us-central1-docker.pkg.dev/<PROJECT>/dgem/dgemma:<tag>
- Remote Google Cloud Endpoint:
export DGEM_VERTEX_URL="<ENDPOINT_ID>" GCP_PROJECT_NUMBER="<PROJECT_NUMBER>" DGEM_GCP_AUTH=1
make build # compiles ./bin/dgem
./bin/dgem decide -t templates/support_triage.json.tmpl \
-v 'ticket=I was billed $500 twice for my annual renewal this morning!' --stats./bin/dgem serve --port 8090Open http://localhost:8090 to browse the templates, try Stage 2 Gemini cascades, and inspect OpenTelemetry trace waterfalls.
Next, pick your path: build, deploy and operate · confidence and calibration · write your first policy.
In one sentence: every
dgemanswer comes with a probability for every allowed option and a hesitation score; clear answers are returned directly and hesitant ones are handed to a larger model or a person. Full explanation:docs/confidence/overview.md.
Hesitation-gating. Hesitation is Shannon entropy scaled to 0–100% by the number of options (bands: <16% clear, 16–50% somewhat unsure, >50% very unsure). Pick a threshold on a labelled sample of your own decisions, answer below it, and hand off above it.
What keeps the probabilities trustworthy.
- The answer template is part of the prompt. Shared option letters across questions can make the model copy answers, and question ids that hint at an answer act as instructions. Use neutral, descriptive ids (authoring).
- Prompt layout. By default the input comes before the questions (
document_first);schema_firstis available per request (prompt layout). - Order bias, measured. The model can favour the first option when unsure; measure flips under shuffled option order on your policies.
- Calibration by domain. The best temperature differs across domains, so fit one per policy (calibrate your policy).
- Changes judged against measured noise. Answers are not fully deterministic. The regression matrix measures run-to-run agreement in every session and judges a candidate against your baseline.
See Decision Studio, MCP and HTTP API and Gateway and routing for full details:
| Interaction Surface | Command / Endpoint | Description |
|---|---|---|
| 1. Decision Studio Web App | ./bin/dgem serve --port 8090 |
Embedded Lit web app with the .json.tmpl decision policies (core, calibration, multimodal, rerank), a backend target selector (vertex_first | vertex | cloudrun), Stage 2 Gemini cascades, approximate image box overlays (coarse, see what dgem can do with images), a plain-English Concepts tab, and OpenTelemetry trace waterfalls. |
| 2. Model Context Protocol (MCP) | ./bin/dgem mcp (stdio)POST /mcp (Streamable HTTP) |
MCP server with tools for policy and custom decisions, template listing, health and warm-up, and image localization, with backend selection and Stage 2 cascade options (cascade_mode, cascade_threshold, cascade_model). |
| 3. HTTP Gateway REST API | POST /api/decide/{template}POST /v1/systemone, GET /api/templates |
Run any .json.tmpl policy or a /v1/systemone decision request with X-DGem-Backend: vertex_first | vertex | cloudrun (X-DGem-Backend-Used is returned on every response) and an optional Stage 2 gemini-3.8-flash cascade. |
| 4. CLI & evaluation harnesses | ./bin/dgem decide --vertex-url ..../bin/dgem bench-* |
Single-pass decisions (--stats, --layout, cascade flags) and evaluation harnesses (bench, bench-intents, bench-calibration, bench-bbox, bench-bbox-judge, bench-guided, bench-vision, bench-jev, bench-decision-index, bench-permutation). |
Teams have historically chosen between two extremes for automated triage, routing, and guardrails:
- Discriminative classifiers and rule systems: very fast, but rigid. A new policy rule or category means new labeled data, retraining, and redeployment.
- Autoregressive LLMs: zero-shot flexible, but they generate answers token by token, can drift from the output format, and their token probabilities are spread across formatting tokens rather than the decision itself.
A zero-shot decision model sits in between. dgem compiles a .json.tmpl template into a fixed diffusion canvas with bidirectional attention; boolean gates, [A–Z] choices, and ordinal scores are read together in one forward pass, and every answer is constrained to the allowed options.
| Dimension | Discrete diffusion decision model (dgem) |
Discriminative classifier | Autoregressive LLM |
|---|---|---|---|
| Policy changes | Edit the .json.tmpl template |
New labels and retraining | Prompt engineering |
| Passes per request | One forward pass for all questions (cost grows with canvas length) | One classifier per attribute | One step per output token |
| Joint conditioning | Bidirectional across questions in a single pass | Independent heads | Left to right only |
| Uncertainty | Per-option probabilities and hesitation; per-domain temperature | Often overconfident out of distribution | Sequence log-probabilities over formatting tokens |
| Stage | Where | Guide |
|---|---|---|
| Crawl | Apple Silicon (diffgemma) or a local NVIDIA GPU |
Run on your laptop |
| Walk | Cloud Run GPU (1× RTX PRO 6000), scale to zero | Deploy on Cloud Run |
| Run | Vertex AI dedicated endpoint, g4-standard-48 + 1× RTX PRO 6000 |
Production on Vertex AI |
A gateway (dgem serve) in front routes to Vertex first and fails over to Cloud Run
(Gateway and routing). Capacity, runbook and observability:
Latency and capacity · Operations runbook.
# Clone the repository
git clone https://github.com/GoogleCloudPlatform/dgem.git
cd dgem
# Compile dgem binary into bin/
make buildEvaluate customer tickets, code changes, or security alerts in a single forward pass:
./bin/dgem decide -t templates/support_triage.json.tmpl \
-v 'ticket=I was billed $500 twice for my annual renewal this morning!' \
--statsExample output (illustrative):
QUESTION | TYPE | VALUE / CHOICE | CONFIDENCE | ENTROPY (H) | AGREEMENT
-----------------------------------------------------------------------------------------
sentiment | score | frustrated | 99.8% | 0.002 nats | 1.00
team | choice | billing | 100.0% | 0.000 nats | 1.00
urgent | boolean | yes | 99.9% | 0.001 nats | 1.00
Standard chat completion with optional thinking mode:
./bin/dgem ask "Explain discrete block diffusion in two sentences."Connect to a remote GCE or Cloud Run GPU service:
./bin/dgem decide \
-u "http://<EXTERNAL_IP>:8080/v1" \
-m "nvidia/diffusiongemma-26B-A4B-it-NVFP4" \
-t templates/support_triage.json.tmpl \
-v 'ticket=Outage: production database cluster unreachable' \
--statsAttach local image paths (automatically base64 encoded) or remote URLs:
./bin/dgem decide -t templates/multimodal/ui_design_review.json.tmpl \
-I fixtures/ui_component.png \
-v 'component=CheckoutCard' \
--statsThe harnesses run against your own endpoint and write a JSON receipt you can replay later
(--from-receipt). Some datasets are fetched at run time instead of being committed
(Run a dataset).
# Multi-field triage (support, code review, security; benchmarks/eval_dataset.jsonl)
./bin/dgem bench -u "<CLOUD_RUN_URL>/v1" --gcp-auth -d benchmarks/eval_dataset.jsonl -M slot -o bench.json
# Calibration and guardrail items (benchmarks/calibration_suite.jsonl, templates/calibration/)
./bin/dgem bench-calibration -u "<CLOUD_RUN_URL>/v1" --gcp-auth -w 4 -o calibration.json
# High-cardinality intents and out-of-scope routing (PolyAI/banking77, clinc150)
./bin/dgem bench-intents --dataset banking77 --full --workers 16
# JevBench public tasks (MIT; downloaded and verified by --sync)
./bin/dgem bench-jev --sync && ./bin/dgem bench-jev -u "<CLOUD_RUN_URL>/v1" --gcp-auth -o jev.jsonTo compare a new serving image or configuration with the one you run today, use the
regression matrix: it runs both in the same session and judges the
difference against the noise it measures. Dataset sources and licences: benchmarks/README.md.
Published at googlecloudplatform.github.io/dgem (index), organized by audience:
- Build, deploy and operate: From laptop to production · Run on your laptop · Use a remote GPU · Build the serving image · Deploy on Cloud Run · Production on Vertex AI · Gateway and routing · Evaluate a deployment · Latency and capacity · Operations runbook · Observability · Regression matrix
- Confidence and calibration: Overview · Calibrate your policy · Confidence beyond Shannon · The journey to decision models · Glossary
- Policies and decisions: Your first decision policy · Authoring and Stage 2 cascades · Run a dataset · Template catalog · Real-world applications · Taxonomy discovery · Images
- Reference: CLI, HTTP and MCP · Studio, MCP and HTTP API · Vertex AI vs. Cloud Run · Apple Silicon engine · How the model decides in one pass
See CONTRIBUTING.md for contributor license agreement (CLA) requirements and community guidelines, and CODE_OF_CONDUCT.md for our Code of Conduct. If you encounter a bug or have feedback on templates or evaluation tools, please open an Issue.
This project is licensed under the Apache-2.0 License. Evaluation datasets derived from third-party sources are located in third_party/ under their respective licenses; see benchmarks/README.md.
Caution
This is not an officially supported Google product. This project is not eligible for the Google Open Source Software Vulnerability Rewards Program.