dgem v0.4.1

Install the CLI

Download a prebuilt static archive (dgem, embedded Decision Studio, templates/, LICENSE, and README.md) and verify its SHA-256 checksum:

OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
ARCH="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"
curl -fsSLO "https://github.com/GoogleCloudPlatform/dgem/releases/download/v0.4.1/dgem_v0.4.1_${OS}_${ARCH}.tar.gz"
curl -fsSLO "https://github.com/GoogleCloudPlatform/dgem/releases/download/v0.4.1/SHA256SUMS"
tar -xzf "dgem_v0.4.1_${OS}_${ARCH}.tar.gz"
./dgem --version

Or install with Go 1.24+:

go install github.com/GoogleCloudPlatform/dgem@v0.4.1
dgem --version

Serving image. No prebuilt images are published yet. Build the serving image from this tag in your own Google
Cloud project with GCP_PROJECT=<PROJECT> make cloudrun-build, then deploy it to Cloud Run GPU or Vertex AI (see
Build the Serving Image and the deploy guides).

---

• Gateway /v1/systemone latency-tail instrumentation and connection pooling (cmd/serve.go, cmd/root.go).
  v1ProxyHandler (POST /v1/systemone and /v1/chat/completions) now emits sequential child spans under
  dgem.gateway.proxy (dgem.gateway.read_body, dgem.gateway.resolve_backend, dgem.gateway.prepare_body,
  dgem.gateway.auth_token, dgem.gpu.proxy_forward, and dgem.gateway.write_response) with request/response byte
  counts, Vertex status probe telemetry (dgem.vertex_status.cache_hit, dgem.vertex_status.source), token cache
  hit/miss (dgem.token.cache_hit), and httptrace upstream connection reuse (dgem.conn.reused, dgem.conn.was_idle,
  dgem.conn.idle_ms). Upstream proxy calls now share a pooled http.Transport (MaxIdleConns: 128,
  MaxIdleConnsPerHost: 64, IdleConnTimeout: 90s) instead of http.DefaultTransport (MaxIdleConnsPerHost: 2).
• Stale-while-revalidate Vertex endpoint status and :rawPredict fast health probe (cmd/serve.go).
  inspectVertexEndpointState serves cached deployed status immediately within a 90s grace window after its 30s
  fresh TTL while refreshing asynchronously in the background (stale_cache), deduplicates concurrent refreshes per
  endpoint ID, extracts project/region directly from Vertex endpoint URLs before querying metadata, and probes fast
  data-plane {"health": true} on :rawPredict endpoints (sending X-DGem-Key when DGEM_SERVER_KEY is configured)
  before falling back to the Vertex endpoints.get control-plane API.
• Prebuilt CLI release archives and go install version reporting (.github/workflows/release.yml, cmd/version.go).
  Pushing a v*.*.* release tag now builds Decision Studio (studio/dist), cross-compiles static CGO_ENABLED=0 dgem
  binaries for linux/amd64, linux/arm64, darwin/amd64, and darwin/arm64 stamped with the release tag and commit
  revision, packages dgem, templates/, LICENSE, and README.md with SHA256SUMS, and attaches them to the
  GitHub Release (creating a draft release if needed). Module-mode go install github.com/GoogleCloudPlatform/dgem@vX.Y.Z
  builds also fall back to Go's embedded module BuildInfo version instead of reporting "dev".
• Interactive documentation landing page and .github/CODEOWNERS (docs-site/src/pages/index.astro, docs-site/public/landing/).
  Adds an interactive GM3 documentation home page featuring a live slot-denoising simulator, Shannon hesitation lab,
  and copy-ready policy workbench, plus repository .github/CODEOWNERS.

dgem v0.4.0

Install the CLI

go install github.com/GoogleCloudPlatform/dgem@v0.4.0

A go install build of v0.4.0 reports dgem version dev (the version is stamped by make build); build from a
checkout of the tag with make build to get dgem version v0.4.0 (revision 4368d3c, built <date>), or install
v0.4.1+ (go install github.com/GoogleCloudPlatform/dgem@latest
now reports the release version, and v0.4.1+ attaches prebuilt static CLI archives).

Serving image. No prebuilt images are published yet. Build the serving image from this tag in your own Google
Cloud project with GCP_PROJECT=<PROJECT> make cloudrun-build, then deploy it to Cloud Run GPU or Vertex AI (see
Build the Serving Image and the deploy guides).

---

Earlier versions were developed internally; this is the first release in this repository.

• Pre-gated prior fusion and co-denoised evidence slots (pkg/decisionindex, dgem systemone serve).
  Questions on /v1/systemone accept optional prior_logits (log-linear Product-of-Experts fusion via
  --prior-weight, --hesitation-gate, and --prior-gate-mode confident|hesitant|proportional|always, preserving
  pre-fusion raw_entropy and raw_normalized_entropy for Stage 2 cascade gating) and evidence_prompt +
  evidence_criteria (co-denoising a companion <question>_evidence slot on the same diffusion canvas, plus
  templates/multimodal/contact_sheet_verify.json.tmpl).
• Wide-option shortlist routing and cosine prior normalization (pkg/decisionindex, dgem systemone serve).
  --shortlist-topk (ShortlistFunc, PriorLogitsShortlist, LexicalOverlapShortlist) resolves wide choice
  questions ($K > 26$) in a single forward pass over the top-$M$ options plus catch-all keys while preserving the
  shortlist's normalized_entropy when lifting probabilities to all $K$ options (falling back to 2-stage bracket
  tournaments when prior_logits is absent). NormalizeCosinePriorLogits converts bi-encoder cosine similarities
  into temperature-scaled log-softmax priors (DefaultCosinePriorTemperature = 0.07), and --shortlist-contrastive
  defaults to false.
• Decision Models Practitioner Guide (docs/practitioners-guide.md). End-to-end architectural guide covering
  Stage-1 restricted-softmax readout, normalized epistemic entropy ($\tilde{H}_m$), graduated production patterns,
  empirical anti-patterns, and deployment topology selection across Apple Silicon, Cloud Run GPU, and Vertex AI.
• Genkit Go v1.14.0 examples (examples/). Runnable standalone module (examples/go.mod) bridging .json.tmpl
  decision policies to Genkit's systemonex (POST /v1/systemone) plugin (examples/dgemgenkit/), including
  hesitation-gated tool-approval interrupts (examples/genkit-tool-approval/) and two-stage gemini-3.8-flash
  synthesis + concurrent bulk dgem evaluation (examples/genkit-bulk-synth/).
• Private (PSC) Vertex AI :rawPredict and single-route serving. The serving image dispatches health
  ({"health": true}), /v1/systemone and OpenAI-shaped chat decisions on its single /predict and /rawPredict
  routes. The CLI, gateway, dgem systemone serve, regression matrix, synthetic probe and contract runner accept
  private PSC Vertex endpoint URLs (http(s)://<ID>-<REGION>-<NUM>.prediction.p.vertexai.goog/v1/projects/.../endpoints/<ID>:rawPredict,
  including plain HTTP on port 80 inside the VPC) and send every call to that single :rawPredict URL.
• Experimental 52-option label sets (az_aa, az_lower). The serving image (DEFAULT_LABELS, request labels)
  and dgem systemone serve --labels support az_aa (A–Z then AA–AZ) and az_lower (A–Z then a–z,
  requests of up to 10 questions) to read up to 52 choice options in one pass and bracket in 52-wide groups above that.
  Default az (A–Z, 26 options) is unchanged.
• Bulk / batch decision recipes and guide. deploy/batch/ adds ready-to-run Cloud Run Jobs, Dataflow (dgem_beam.py)
  and fan-out workers (batch_worker.py, sending X-DGem-Key from DGEM_SERVER_KEY in remote mode), documented in
  To batch or not to batch.
• New policy template: templates/github_spam_triage.json.tmpl (single-pass spam gate + 9-way category classification
  for GitHub issues, PRs and discussions).
• Adapter server time telemetry: evaluation_trace.server_ms sums diagnostics.timing.total_ms across passes; the
  matrix latency runner records server p90/p95/p99 alongside wall time.
• /v1/systemone: per-caller pass-through for requests the serving image can answer as sent.
  --systemone-raw-users / DGEM_SYSTEMONE_RAW_USERS (comma-separated verified identities, * for all; default
  none) forwards a listed caller's adapter-mode request unchanged when it has at most 8 questions, every choice and
  score has 2-26 options or levels, and types are literally choice/noul/score (media is converted to images).
  Other requests still use the adapter. Why: the adapter builds a different prompt (a text state wrapped as JSON,
  questions and options sorted, its own instructions) and response shape (no yes/no probabilities, sorted keys, no
  model/usage) than the serving image, which changed a client's small-turn answers when score questions were added
  to the adapter. The span log records dgem.systemone.mode (passthrough or adapter).
• Serving image: optional service key (X-DGem-Key). With DGEM_SERVER_KEY set (comma-separated to rotate),
  every POST needs a matching X-DGem-Key header; GET /health stays open. Unlike API_KEY it works on Vertex AI
  and Cloud Run, where Authorization carries the Google token. The dgem CLI, the gateway, dgem systemone serve,
  scripts/matrix, probe.py, serving_speed.py and contract_diff.py send the first entry of their own
  DGEM_SERVER_KEY; the gateway never forwards a caller's header. The Vertex AI, Cloud Run, gateway and probe deploy
  scripts set it from the Secret Manager secret dgem-server-key when it exists (SERVER_KEY_SECRET names another).
  Use it for any endpoint that more than your own services can reach, such as a Vertex AI dedicated endpoint
  (Vertex AI).
• Gateway: caller authentication. dgem serve --iap-audience (DGEM_IAP_AUDIENCE) verifies the IAP JWT on every
  request (signature, audience, expiry) and takes the caller's identity from it, discarding identity headers sent by
  the client; --api-keys (DGEM_GATEWAY_KEYS, header X-DGem-Api-Key) serves self-hosted gateways without IAP.
  With either set, requests without valid credentials get 401, with the same body whatever is configured (the
  accepted methods are printed at startup). GET /health stays open and reports only liveness, the version and
  whether body logging is on. Behaviour change: it no longer lists default_backend, upstream_url or
  vertex_url; GET /api/backend-config reports them, the upstream URL as cloudrun_url.
  deploy_cloudrun_gateway.sh sets the Cloud Run IAP audience by default (VERIFY_IAP=0 to skip). Callers set
  DGEM_GATEWAY_KEY: the CLI sends it only to the gateway in DGEM_GATEWAY_URL (same scheme, host and port) and
  dgem mcp --remote to its remote. No dgem client keeps X-DGem-Api-Key or X-DGem-Key on a redirect to another
  origin, and the gateway never forwards a caller's key upstream. Without either option the gateway warns at startup
  when it listens on a non-loopback address.
• Image URLs are fetched by dgem, never by the serving image. The gateway (/api/decide, MCP, /api/locate,
  /v1/systemone including ?raw=1, and the /v1/chat/completions proxy) fetches http(s) image URLs with its
  public-address-only client and forwards data: URIs (unfetchable or non-image URLs: 422); the CLI fetches from the
  caller's network and does the same. Behaviour change: the serving image refuses http(s) image URLs with 400 by
  default (DGEM_IMAGE_URLS=deny; allow restores the old behaviour), because vLLM runs with network egress and a URL
  that passed the gateway's check could rebind or redirect to the metadata server or internal hosts.
• Audio and video are refused with 400 by the serving image, the gateway and dgem systemone serve (audio,
  video, input_audio, video_url and similar fields or chat content parts), instead of being answered as if they
  were absent. Send video as sampled frames in images and audio as a transcript.
• Requests the model server refuses are 4xx, not 500/502. The serving image answers 422 (400 on the chat route)
  when vLLM refuses a request, such as an image it can't fetch or decode or a prompt over the context length; the
  gateway and dgem systemone serve pass such refusals on with the server's message. Behaviour change:
  /api/decide returns 422 instead of 502 for them and no longer retries them as cold starts; unreachable or failing
  servers stay 502. The gateway API reference documents the 400/401/422/502 meanings.
• /v1/systemone adapter: score questions, one-option questions, media.
  • score questions (criteria an array of levels) are read with the rest in batches of at most 8; answers follow
    the serving image's form (score = sum(i·p_i), probabilities keyed "0".."n-1", legend). Every answer now
    carries confidence.
  • A choice with one option or a score with one level is answered without a model call.
  • media: [{mime_type, data}] with image/* (data: URI or raw base64) is an alias for images; other types get 400....