DEV Community: Robina Mirbahar

Building RailPulse AI: Deploying an Open-Source Railway Dispatch Agent with Gemma and Google Cloud Run

Robina Mirbahar — Sat, 07 Nov 2026 07:35:33 +0000

Author: Robina Mirbahar

AI/ML Google Developer Expert (GDE) | Google Cloud Champion Innovator

GitHub Blueprint: RobinaMirbahar/railpulse-gemma-cloudrun

YouTube Walkthrough: @RobinaCodesAI

Robina Mirbahar presenting RailPulse AI, Gemma 4, and Cloud Run at DevFest Baku 2026, ADA University.

Most artificial intelligence tutorials show you how to build chatbots that write poems, summarize PDFs, or generate boilerplate code.

Those demos are fun, but they do not reflect the harsh reality of engineering in mission-critical industries.

When you deploy AI to manage physical operations, like freight trains moving across thousands of kilometers, a generic chatbot is not just useless; it can be dangerous. A hallucinated speed limit or a delayed signal alert can lead to catastrophic hardware failure or derailment.

At DevFest Baku 2026 at ADA University, I wanted to show developers how to build an enterprise-grade AI system that solves a real operational problem. We built and deployed RailPulse AI, an autonomous, safety-critical railway dispatch and live-tracking agent powered by Google's open-weights Gemma models, the Google Agent Development Kit (ADK), and Google Cloud Run.

In this article, I will walk you through the complete architecture, how we used function calling with deterministic safety interlocks, and how you can run open-weights agents serverlessly in production.

The Real-World Engineering Problem

Railway corridors run on tight margins. Dispatchers must continuously monitor:

Real-Time Telemetry: GPS coordinates, axle bearing temperatures, and locomotive velocity.
Corridor Weather Extremes: Sudden crosswinds along coastal or mountain tracks.
Schedule Recovery: Balancing delays against passenger connection deadlines and single-track passing sidings.

When an emergency happens, dispatchers do not have time to sift through fragmented SCADA dashboards and thousand-line logs. They need an intelligent system that aggregates live telemetry, cross-references signaling rules, and synthesizes clear, actionable dispatch advisories.

Crucially, the system cannot hallucinate. It must combine the natural reasoning of an LLM with the deterministic predictability of hard-coded safety rules.

The RailPulse AI Architecture

Here is the high-level system design we implemented in RobinaMirbahar/railpulse-gemma-cloudrun:

┌─────────────────────────────────────────────────────────────┐
│                 Streamlit Operator Cockpit                  │
│       Interactive SVG Gauges • Multi-Language (EN/AZ/RU)    │
└──────────────────────────────┬──────────────────────────────┘
                               │ HTTPS / JSON
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                 Google Cloud Run Service                    │
│                                                             │
│   ┌─────────────────────────────────────────────────────┐   │
│   │             Google ADK Agent Orchestrator           │   │
│   │                                                     │   │
│   │  ┌─────────────────┐       ┌─────────────────────┐  │   │
│   │  │   Gemma Model   │ ◄───► │  Tool Declarations  │  │   │
│   │  │  (Open-Weights) │       │   Function Calling  │  │   │
│   │  └─────────────────┘       └──────────┬──────────┘  │   │
│   └───────────────────────────────────────┼─────────────┘   │
│                                           ▼                 │
│   ┌─────────────────────────────────────────────────────┐   │
│   │       Deterministic Safety Interlocks (Python)      │   │
│   │   • Hard Wind Speed Limits (Wind > 65 km/h -> 80)   │   │
│   │   • Absolute Signal Overrides (Red Signal = STOP)   │   │
│   │   └───────────────────────────────────┬─────────────┘   │
│                                           ▼                 │
│   ┌─────────────────────────────────────────────────────┐   │
│   │         Pydantic Structured Advisory Schema         │   │
│   │           RailDispatchAdvisory Validation               │   │
│   └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

1. Grounding the Agent: Real-World Tools via Function Calling

Rather than letting Gemma guess railway conditions, we gave the agent access to dedicated telemetry tools using Google ADK function calling:

def get_live_train_telemetry(train_id: str) -> dict:
    """Fetch live GPS, speed, bearing temperatures, and locomotive health."""
    pass

def check_corridor_signals_and_wind(corridor_id: str) -> dict:
    """Query wayside signal states (Green/Yellow/Red) and track anemometers."""
    pass

def calculate_schedule_recovery(train_id: str, current_delay_min: int) -> dict:
    """Calculate speed profiles needed to recover schedule without exceeding corridor limits."""
    pass

When an operator asks:

"Train 102 is approaching the Absheron corridor 14 minutes behind schedule. Can we accelerate to recover time?"

Gemma does not guess. It autonomously calls check_corridor_signals_and_wind(corridor="Absheron") and get_live_train_telemetry(train_id="102") to gather factual state before generating a response.

2. Deterministic Safety Interlocks: Why the LLM Does Not Make the Final Safety Call

In physical systems, you never give an LLM sole authority over life-safety decisions.

If the model experiences a temporary context confusion, it might suggest maintaining 140 km/h in a 90 km/h windstorm. To prevent this, we built a two-tier architecture:

Tier 1 (Cognitive Reasoning): Gemma analyzes the situation, extracts the context, and proposes a schedule recovery plan.
Tier 2 (Deterministic Guardrails): A hard-coded Python interlock inspects the output against physical invariants before delivering the advisory:

class SafetyInterlock:
    MAX_HIGH_WIND_SPEED_KMH = 80.0
    HIGH_WIND_THRESHOLD_KMH = 65.0

    @classmethod
    def enforce_guardrails(cls, advisory: RailDispatchAdvisory, wind_speed: float, signal_state: str) -> RailDispatchAdvisory:
        # Rule 1: High Wind Speed Clamp
        if wind_speed >= cls.HIGH_WIND_THRESHOLD_KMH:
            if advisory.recommended_speed_kmh > cls.MAX_HIGH_WIND_SPEED_KMH:
                advisory.recommended_speed_kmh = cls.MAX_HIGH_WIND_SPEED_KMH
                advisory.safety_flags.append(
                    f"GUARDRAIL ENFORCED: Wind speed {wind_speed} km/h exceeds threshold. Speed clamped to 80 km/h."
                )

        # Rule 2: Absolute Red Signal Override
        if signal_state == "RED":
            advisory.recommended_speed_kmh = 0.0
            advisory.action_required = "EMERGENCY_STOP"
            advisory.safety_flags.append("CRITICAL: Red signal detected. Immediate stop enforced.")

        return advisory

This guarantees that even if an operator or a prompt edge case attempts to push the model beyond safe boundaries, the mathematical and physical guardrails cannot be bypassed.

3. Strict Output Contracts with Pydantic

To ensure the downstream operator dashboard never crashes due to unstructured freeform text, all agent advisories are validated against a strict schema:

from pydantic import BaseModel, Field
from typing import List, Optional

class RailDispatchAdvisory(BaseModel):
    train_id: str
    recommended_speed_kmh: float = Field(..., ge=0.0, le=160.0)
    delay_delta_minutes: int
    signal_status: str
    action_required: str
    advisory_summary: str
    safety_flags: List[str] = []
    confidence_score: float = Field(..., ge=0.0, le=1.0)

If the agent’s response does not conform to this structure, the ADK pipeline rejects it before it ever reaches the dispatcher cockpit.

4. Packaging and Deploying on Google Cloud Run

To make RailPulse AI truly production-ready, we containerized the application with Docker and deployed it to Google Cloud Run.

Why Cloud Run for AI Agents?

Serverless Economics: Rail telematics spikes during train arrivals and yard movements, with quiet periods in between. Cloud Run scales dynamically from zero to handle spikes and scales back down when traffic subsides.
Air-Gapped and Sovereign Edge Ready: Because Gemma is an open-weights model, you can run inference entirely inside your own private VPC without sending sensitive operational telemetry to third-party proprietary APIs.
One-Command Deployment:

gcloud run deploy railpulse-agent \
    --source . \
    --platform managed \
    --region europe-west1 \
    --allow-unauthenticated \
    --memory 4Gi \
    --cpu 2

5. Localized Operator Experience: Multi-Language Dispatch (EN / AZ / RU)

In international logistics corridors like the Trans-Caspian International Transport Route, operators speak multiple languages.

Because Gemma possesses strong multilingual representations, RailPulse AI seamlessly provides telemetry readouts, safety flags, and advisory summaries in English, Azerbaijani (Azərbaycan dili), and Russian (Русский), allowing local dispatchers to interact with the system in their native language while maintaining uniform safety semantics under the hood.

Key Lessons from Building RailPulse AI

Building this project and presenting it at DevFest Baku reinforced three fundamental principles for building agentic AI:

Agents are More Than Prompts: A production agent is 20% prompt engineering and 80% systems engineering: tool definitions, schema validation, network resilience, and error handling.
Deterministic Guardrails are Mandatory: In physical, industrial, or medical applications, never let an LLM have unchecked authority. Pair cognitive reasoning with deterministic code interlocks.
Open-Weights Models are Production Ready: With models like Gemma and serverless platforms like Google Cloud Run, individual developers and enterprise teams can build custom, private, and fully auditable AI systems without paying thousands of dollars in proprietary API costs.

Explore the Code and Video Walkthrough

The complete codebase, Streamlit operator dashboard, Dockerfile, and Google ADK implementation are open-source and ready to clone:

GitHub Repository: https://github.com/RobinaMirbahar/railpulse-gemma-cloudrun
YouTube Channel: https://www.youtube.com/@RobinaCodesAI

Special thanks to the GDG Baku team, ADA University, and all the incredible participants at DevFest Baku 2026 for making this hands-on workshop such a rewarding experience!

MemoriaViva: A Cute Ghost in the Machine That Preserves Family Oral Histories & Heirloom Recipes with Gemma 4 & Google ADK

Robina Mirbahar — Tue, 27 Oct 2026 20:05:29 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

Every family has a "Ghost in the Machine" waiting to be remembered: a crackly 48-second WhatsApp voice note from a grandfather explaining how to brew monsoon ginger kahwa, a flour-stained index card in a grandmother's handwriting where measurements are written as "two cupped handfuls of wheat flour and warm milk until the dough sighs softly," or a shoebox of fading photographs from decades ago.

MemoriaViva (Living Memory) is a warm, local-first Family Oral-History Weaver, Heirloom Recipe Standardizer & Digital Family Storybook powered by open-weights Google Gemma 4 (google/gemma-4-27b-it), Google Agent Development Kit (ADK), Google BigQuery (Family Vault table schema), and Sentry Agent Tracing.

I interpreted this week's theme in the warm spirit of Dia de los Muertos and South Asian ancestral remembrance: Lumi, a friendly, spectacle-wearing memory ghost living on the same machine that reads fragmented family voice transcripts and handwritten recipe notes, preserves the elder's exact cultural idioms verbatim, converts poetic ancestral measurements ("a three-finger pinch of saffron," "four brimming clay bowls of flour") into reproducible metric grams and milliliters, and exports a Dual-Mode Family Vault consisting of a self-contained W3C HTML5 Family Storybook (4,909 bytes) plus a Google BigQuery Newline-Delimited JSON (exported_memories.jsonl, 4,344 bytes) table export.

Heritage Archival Metric	Raw Family Voice Notes & Index Cards	MemoriaViva (Gemma 4 + Google ADK + BigQuery Vault)
Ancestral Measurement Format	Ambiguous ("a handful," "a teacup," "until soft")	Dual-Format: Verbatim Poetic Phrase + Exact Metric (`g` / `ml`)
Poetic Units Converted in Benchmark	9 unstructured phrases across 3 family recipes	9 of 9 (100.0% deterministic metric conversion)
Dough & Liquid Hydration Validation	Guesswork (often fails for younger generations)	Deterministic Culinary Ratio Guardrail (45.0% to 95.0% bounds)
Local Inference Privacy	Uploaded to third-party commercial LLM APIs	0 bytes Transmitted (127.0.0.1 Air-Gap Socket Lock)
Family Vault Storage	Locked in proprietary SaaS apps	Local W3C HTML5 (4,909 B) + BigQuery JSONL Vault Table (4,344 B)

Demo

You can run the complete MemoriaViva three-stage Gemma 4 + Google ADK + Sentry Agent Tracing benchmark, verify the interactive FastAPI Family Storybook Dashboard, and export both the offline HTML5 book and the Google BigQuery JSONL Family Vault with a single command:

python scripts/run_memoriaviva_demo.py

========================================================================================
👻🕯️ MEMORIAVIVA: CUTE GHOST IN THE MACHINE (GEMMA 4 + ADK + BIGQUERY VAULT)
========================================================================================
  Model                  : google/gemma-4-27b-it (100% Local Ollama / vLLM)
  Air-Gapped Endpoint    : http://127.0.0.1:11434 (0 Cloud Egress Verified)
  Family Memories Loaded : 3 ancestral voice & recipe records
----------------------------------------------------------------------------------------
  [MEM-01] Dadi Jan's Partition-Era Cardamom & Saffron Sweet Bread (1947)
    Elder Quote Preserved : 'Measure the warm milk with your fingertips; when the dough sighs softly, the cardamom is awake.'
    • 'two generous cupped handfuls of stone-ground wheat flour'  ➔  240.0g Stone-Ground Whole Wheat Flour (Atta)
    • 'one brass teacup of lukewarm milk tested with your fingertip'  ➔  180.0ml Whole Warm Milk (38C)
    • 'seven bruised green cardamom pods & a three-finger pinch of saffron'  ➔  4.4g Crushed Green Cardamom & Kashmiri Saffron
    Hydration Audit       : 75.0% | Sentry Trace: 49ef09ebc06d4014
----------------------------------------------------------------------------------------
  [MEM-02] Abuelo Mateo's Dia de los Muertos Cinnamon Pan de Muerto (1968)
    Elder Quote Preserved : 'Roll the dough bones slowly while telling the children how your great-grandfather built the adobe oven.'
    • 'four brimming clay bowls of bread flour'  ➔  500.0g Unbleached Artisan Bread Flour
    • 'a warm splash of orange blossom water & melted butter'  ➔  325.0ml Orange Blossom Infusion & Warm Milk
    • 'two thumbs of freshly grated orange zest and Ceylon cinnamon'  ➔  12.0g Organic Orange Zest & Ground Cinnamon
    Hydration Audit       : 65.0% | Sentry Trace: e480da38d4c544bf
----------------------------------------------------------------------------------------
  [MEM-03] Nana's Monsoon Ginger-Saffron Healing Kahwa (1982)
    Elder Quote Preserved : 'Never boil the crushed almonds before the first rain hits the courtyard stone; let the steam carry the clove aroma.'
    • 'three copper cups of spring water'  ➔  600.0ml Filtered Spring Water
    • 'a thumb-sized root of crushed fresh ginger & four cloves'  ➔  18.0g Fresh Crushed Ginger & Whole Cloves
    • 'a palmful of slivered almonds and wildflower honey'  ➔  37.0g Blanched Slivered Almonds & Raw Honey
    Hydration Audit       : 100.0% | Sentry Trace: fbfe81215ad54101
----------------------------------------------------------------------------------------
  Poetic Units Converted : 9 of 9 (100.0% deterministic metric accuracy)
  Sentry Spans Recorded  : 18 gen_ai.agent / gen_ai.tool spans
  FastAPI Ofrenda Check  : GET / (200 OK) | GET /api/memories (200 OK)
  Family Vault Export    : 4909 bytes HTML5 + 4344 bytes BigQuery JSONL (3 rows)
  Cloud Bytes Transmitted: 0 bytes during local Gemma 4 inference
========================================================================================

Interactive Family Storybook & Recipe Weaver UI Preview

Code

RobinaMirbahar / memoriaviva-gemma-ofrenda

MemoriaViva: Cute Ghost in the Machine — 100% Local Open-Weights Gemma 4, Google ADK & Sentry Agent Tracing Family Oral-History & Heirloom Recipe Weaver (Hacktoberfest 2026)

👻🕯️ MemoriaViva: Cute Ghost in the Machine for Family Oral Histories & Heirloom Recipes (Gemma 4 + Google ADK + BigQuery Family Vault)

Author & Architect: Robina Mirbahar (Google Developer Expert in Cloud & AI · Google Cloud Champion Innovator · Author of AI Engineering)
Challenge Track: Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine (#hf26challenge, #gemma, #googleai)
Core Stack: Open-Weights Google Gemma 4 (google/gemma-4-27b-it), Google Agent Development Kit (ADK), Google BigQuery (JSONL Family Vault Table), Google AI Studio, FastAPI, Pydantic v2, and Sentry Agent Tracing.

📊 Live Architecture Telemetry & Benchmark Highlights

Heritage Archival Metric	Raw Family Voice Notes & Index Cards	MemoriaViva (Gemma 4 + Google ADK + BigQuery Vault)
Ancestral Measurement Format	Ambiguous ("a handful," "a teacup," "until soft")	Dual-Format: Verbatim Poetic Phrase + Exact Metric (`g` / `ml`)

…

View on GitHub

Repository Structure

memoriaviva-gemma-ofrenda/
├── memoriaviva/
│   ├── __init__.py
│   ├── schemas.py        # Pydantic v2 schemas for RawFamilyMemory & WovenHeirloomStoryCard
│   ├── guardrails.py     # Air-gapped 127.0.0.1 socket lock & culinary hydration validator
│   ├── agents.py         # 3-stage Google ADK SequentialAgent + Gemma 4 + Sentry Tracer
│   └── dashboard.py      # FastAPI Family Storybook & static HTML5 exporter
├── scripts/
│   └── run_memoriaviva_demo.py  # Benchmark + HTML5 & BigQuery JSONL Family Vault exporter
├── articles/memoriaviva/        # Illustrations, BigQuery schema & benchmark evidence
└── requirements.txt

How I Built It

I built MemoriaViva by combining Google's open-weights AI ecosystem and Google Cloud data architecture with deterministic Python safety guardrails:

Open-Weights Google Gemma 4 (google/gemma-4-27b-it):
- Configured for local serving via Ollama / vLLM on http://127.0.0.1:11434.
- Gemma 4 preserves South Asian (Urdu/Sindhi) and Latin American (Spanish) culinary idioms alongside structured JSON output.
Google Agent Development Kit (ADK) 3-Stage SequentialAgent Pipeline (memoriaviva/agents.py):
- Stage 1 (OralHistoryWhisperAgent): Extracts the elder's verbatim quote and weaves the historical context (1947 Partition-era Hyderabad, 1968 Oaxaca Dia de los Muertos, 1982 Monsoon Courtyard) into a structured narrative.
- Stage 2 (HeirloomRecipeAlchemistAgent): Translates tactile, non-standard measurements ("two generous cupped handfuls of stone-ground wheat flour") into structured StandardizedIngredient objects (240.0g) while keeping the original phrase beside it.
- Stage 3 (CandlelitOfrendaCuratorAgent): Validates the memory against WovenHeirloomStoryCard and prepares the record for the Family Vault.
Deterministic Privacy & Culinary Guardrails (memoriaviva/guardrails.py):
- verify_air_gapped_endpoint(): Rejects any non-local hostname (127.0.0.1 / localhost / ::1) during inference, guaranteeing that 0 bytes of raw family recordings are sent to external LLM APIs.
- compute_and_validate_hydration(): Audits the ratio of liquid milliliters to dry flour grams (75.0% for MEM-01, 65.0% for MEM-02, and 100.0% for liquid infusion MEM-03) within deterministic bounds (45.0% to 95.0% for doughs).
Dual-Mode Family Vault (Local W3C HTML5 + Google BigQuery Table Schema):
- By default, scripts/run_memoriaviva_demo.py writes the woven memories to a self-contained W3C HTML5 Family Storybook (4,909 bytes) and a Newline-Delimited JSON (exported_memories.jsonl, 4,344 bytes) file alongside bigquery_vault_schema.json.
- Because standardized_recipe is structured as a RECORD REPEATED nested array, families who want to back up their structured cookbook across continents in their own private Google Cloud project can load the JSONL archive directly into a Google BigQuery table (memoriaviva_vault.heirloom_memories):

bq load --source_format=NEWLINE_DELIMITED_JSON \
  memoriaviva_vault.heirloom_memories \
  articles/memoriaviva/evidence/exported_memories.jsonl \
  articles/memoriaviva/evidence/bigquery_vault_schema.json

Sentry Agent Tracing (LocalSentryTracer):
- Every stage emits OpenTelemetry-compatible gen_ai.agent and gen_ai.tool spans capturing model name, ingredient conversion counts, and hydration audit results across all 18 recorded spans.

def verify_air_gapped_endpoint(endpoint_url: str) -> Tuple[bool, str]:
    """Ensure inference requests only target local open-weights endpoints."""
    parsed = urlparse(endpoint_url)
    allowed_hosts = {"127.0.0.1", "localhost", "::1"}
    if parsed.hostname in allowed_hosts:
        return True, f"AIR_GAP_OK: {parsed.hostname} is strictly local (0 cloud bytes)."
    raise PermissionError(
        f"PRIVACY_GUARDRAIL_BLOCKED: External host '{parsed.hostname}' rejected to protect family archive."
    )

Why Does Open Innovation Matter?

For a project that handles intimate family memories, elders' voices, and ancestral heritage, open-weights AI provides three concrete engineering guarantees:

Intimate Family Voices Stay on 127.0.0.1 (0 bytes LLM Cloud Egress): Families can transcribe and structure voice notes locally with Gemma 4 without uploading private recordings to a third-party commercial LLM API.
Works Offline in Courtyards, Villages & Field Recordings: When visiting elders in rural towns or recording oral histories without internet connectivity, the local Gemma 4 + Google ADK pipeline runs offline on the same machine.
Open Standards + Private Google BigQuery Family Vault Ownership: By exporting a self-contained W3C HTML5 file (4,909 bytes) alongside a Google BigQuery JSONL archive (4,344 bytes), your family owns both an offline browser-ready book and a structured analytical table under your own IAM control.

My Agent Session

During the benchmark run, MemoriaViva recorded 18 structured gen_ai.agent and gen_ai.tool spans across the 3-stage Google ADK + Gemma 4 pipeline:

gen_ai.agent ➔ OralHistoryWhisperAgent (model="google/gemma-4-27b-it", memory_id="MEM-01")
gen_ai.tool ➔ HeirloomRecipeAlchemistAgent.standardize_units (ingredients_converted=3, hydration_pct=75.0)
gen_ai.agent ➔ CandlelitOfrendaCuratorAgent (air_gapped=True, trace_id="49ef09ebc06d4014")

The Spirit of It

In almost every culture, from Dia de los Muertos ofrendas glowing with marigolds in Mexico to family hearths across South Asia, food and storytelling are how we keep the people we love close to us.

When an elder writes "measure the warm milk with your fingertips; when the dough sighs softly, the cardamom is awake," standard recipe apps strip away the voice and leave cold numbers. Conversely, keeping only the poetic phrase leaves younger generations unsure how much "two cupped handfuls" weighs. Seeing Gemma 4 preserve both side-by-side (240.0g Stone-Ground Whole Wheat Flour and 180.0ml Whole Warm Milk at 75.0% hydration alongside Dadi Jan's exact words) inside a self-contained digital family book and BigQuery Family Vault brought this project to life.

Prize Categories

Best Use of Gemma: Uses open-weights google/gemma-4-27b-it as the core reasoning design inside a 3-stage Google ADK pipeline to preserve multilingual oral histories and deterministically standardize 9 of 9 (100.0%) ancestral culinary measurements locally.
Best Use of Sentry Agent Tracing: Instruments every Google ADK agent and tool stage with 18 gen_ai.agent and gen_ai.tool telemetry spans to audit conversion accuracy and hydration guardrails locally.

From Ancient Epigraphy to 3D Proteins: Exploring google-deepmind/science-skills & Building Custom Plugins in Google Antigravity

Robina Mirbahar — Sat, 24 Oct 2026 18:56:58 +0000

What happens when you ask an AI coding agent to score a non-coding human genomic variant with AlphaGenome, map a missense mutation onto an AlphaFold 3D protein structure, screen ChEMBL for nanomolar small-molecule inhibitors, or restore a damaged 2,000-year-old Roman inscription using Google DeepMind's Aeneas model?

If you try to stuff 40 scientific APIs, rate limiters, clinical safety guardrails, and 3D WebGL visualizers into a single mega-prompt, the agent collapses under context bloat and hallucinated parameters.

Google Antigravity solves this at the runtime level with its Plugin & Customization Architecture - combining Progressive-Disclosure Skills (SKILL.md), Always-On Rules (AGENTS.md), Lifecycle Hooks (hooks.json), Zero-Leak Credential Protocols, and Model Context Protocol (mcp_config.json) + Background Sidecars (sidecar.json).

Instead of just reading the docs, I explored the newly open-sourced Google DeepMind Science Skills (google-deepmind/science-skills, v1.3.1) repository (Apache 2.0 / CC-BY 4.0) and built the open-source Antigravity Science Plugin Cookbook & Interactive 3D Studio - complete with a live browser-based 3D Biomolecular & Variant WebGL Sandbox, a zero-dependency PEP 723 3D protein + PAE generator, and a production bio-structural-qc custom plugin.

Try the Live 3D Biomolecular & MCP Sidecar Studio in Your Browser

Launch the Interactive 3D Biomolecular & Variant WebGL Studio (index.html)
- Explore 3D C-alpha backbones & non-covalent contact networks for TP53 (AF-P04637), Crambin (1CRN), and EGFR Kinase + Gefitinib (CHEMBL203).
- Click any 3D residue sphere via raycasting to trigger live annotate_region MCP tool calls, inspect AlphaFold pLDDT & AlphaGenome Variant Impact (AVI) scores, upload your own .pdb/.cif files, or run the interactive Aeneas Latin Epigraphy restoration demo!
Full Source Code & bio-structural-qc Plugin on GitHub (RobinaMirbahar/antigravity-science-plugin-cookbook)

1. The Antigravity Customization Architecture & Context Economics

Why can the Science plugin bundle 40 complex scientific skills and a 9-tool 3D WebGL MCP server without slowing down everyday coding turns? Because Antigravity strictly separates always-on behavioral guardrails from on-demand procedural execution:

The 5 Customization Primitives & Their Token Budgets

Primitive	Config File / Path	Loading Behavior	Token Budget & Engineering Role
Rules	`GEMINI.md`, `AGENTS.md`, `rules/AGENTS.md`	Always-On (within directory or active plugin scope)	Contextual rules loaded automatically for their active workspace or plugin scope, deduplicated by resolved file path.
Skills	`skills/<name>/SKILL.md`	Progressive Disclosure (On-Demand)	Only the YAML `name` and `description` (~40-80 tokens) are injected into the system prompt. The full `SKILL.md` and `references/` are read only when activated.
Plugins	`plugins/<dir>/plugin.json`	Atomic Bundle	Namespaces and toggles related `skills/`, `rules/`, `hooks.json`, `mcp_config.json`, and `sidecars/` as a single unit.
Hooks	`hooks.json` (at plugin or `.agents/` root)	Lifecycle Event Triggers	Intercepts `SessionStart`, `PreInvocation`, `PreToolUse`, `PostToolUse`, `PostInvocation`, and `Stop` to run shell validators, audit loggers, or linters.
MCP & Sidecars	`mcp_config.json` + `sidecars/<name>/sidecar.json`	Tool + UI Integration	Connects local (`stdio`) or remote (`Streamable HTTP`) tool servers (`mcp_config.json`) and manages persistent background sidecar processes (`sidecar.json`).

2. Inside the Open-Source `google-deepmind/science-skills` Repository (`v1.3.1`)

You can enable the Science bundle directly in Google Antigravity (Customizations > Build with Google > Science > Add) or install it via npx skills add google-deepmind/science-skills/ from github.com/google-deepmind/science-skills. Look at how cleanly plugin.json and the 40 open-source skills are organized:

google-deepmind/science-skills/ (installed at ~/.gemini/config/plugins/science/)
├── plugin.json                                  # Bundle manifest (name, description, $schema)
├── LICENSE                                      # Apache 2.0 & CC-BY 4.0 Open-Source Licenses
├── README.md                                    # User-facing setup & documentation
├── SKILL_LICENSES.md                            # Third-party database attribution & terms
└── skills/                                      # 40 Progressive-Disclosure Scientific Skills
    ├── alphafold_database_fetch_and_analyze/    # pLDDT & sliding-window PAE domain heuristics
    ├── alphagenome_atlas_website_links/         # Deep-links to AlphaGenome Atlas
    ├── alphagenome_single_variant_analysis/     # RNA-seq, DNASE, ChIP & splicing effects
    ├── alphagenome_variant_impact_score/        # AVI scoring, VCF annotation, GENCODE v46 GTF
    ├── chembl_database/                         # Bioactivity (IC50/Ki), targets, drug mechanisms
    ├── clinical_trials_database/                # ClinicalTrials.gov APIv2 queries
    ├── clinvar_database/                        # Pathogenicity & clinical review status
    ├── credentials/                             # Zero-leak .env verification protocol
    ├── dbsnp_database/                          # rsID <-> GRCh38 VCF/HGVS resolution
    ├── embl_ebi_ols/                            # 250+ biomedical ontologies (GO, HP, DOID)
    ├── encode_ccres_database/                   # ENCODE SCREEN GraphQL & cis-regulatory elements
    ├── ensembl_database/                        # Gene/transcript lookup, sequences & VEP
    ├── foldseek_structural_search/              # 3D structure similarity search (.cif/.pdb)
    ├── gnomad_database/                         # Allele frequencies & gene constraint (pLI/LOEUF)
    ├── gtex_database/                           # Tissue-specific RNA expression & eQTLs
    ├── human_protein_atlas_database/            # Spatial & tissue protein expression
    ├── interpro_database/                       # Protein domains, families & InterPro-N
    ├── jaspar_database/                         # TF binding profiles (PFMs/PWMs)
    ├── literature_search_arxiv/                 # arXiv preprints & full-text extraction
    ├── literature_search_biorxiv/               # bioRxiv / medRxiv narrow-window search
    ├── literature_search_europepmc/             # Europe PMC XML/PDF & citation graphs
    ├── literature_search_openalex/              # Bibliometrics, citation counts & OA PDFs
    ├── ncbi_sequence_fetch/                     # NCBI E-utilities nucleotide/protein fetch
    ├── openfda_database/                        # 28 FDA endpoints (adverse events, 510k, NDC)
    ├── opentargets_database/                    # Target-disease associations & tractability
    ├── pdb_database/                            # Experimental 3D structures from RCSB PDB
    ├── predictingthepast/                       # Aeneas (Latin) & Ithaca (Ancient Greek) epigraphy
    ├── protein_sequence_msa/                    # EBI Clustal Omega multiple sequence alignment
    ├── protein_sequence_similarity_search/      # MMseqs2 (fast) & BLAST homology search
    ├── pubchem_database/                        # SMILES/CID chemical properties & substructures
    ├── pubmed_database/                         # NCBI PubMed + PMC BioC full-text linking
    ├── pymol/                                   # Headless PyMOL rendering & structural superposition
    ├── quickgo_database/                        # Gene Ontology & ECO evidence mapping
    ├── reactome_database/                       # Pathway enrichment & reaction participants
    ├── string_database/                         # Protein-protein interaction (PPI) networks
    ├── ucsc_conservation_and_tfbs/              # phyloP, phastCons & ENCODE/JASPAR/ReMap TFBS
    ├── unibind_database/                        # Experimentally validated direct TF-DNA binding
    ├── uniprot_database/                        # UniProtKB/UniParc/UniRef metadata & sequences
    ├── uv/                                      # Prerequisite uv environment bootstrapper
    └── workflow_skill_creator/                  # Interactive distiller: turns chat workflows into skills

3. Five Production Engineering Patterns Inside the Science Plugin

While inspecting the source files across all 40 skills, five engineering patterns stood out that every Google Cloud and agentic AI builder can adopt.

Pattern 1: Always-On Behavioral Routing via `rules/AGENTS.md`

As documented in the public Antigravity Rules Guide (antigravity.google/docs/rules), rules define persistent coding standards and architectural constraints (always_on, model_decision, glob, or manual) that automatically apply within their configured workspace or plugin scope.

In my custom bio-structural-qc plugin (plugins/bio-structural-qc/rules/AGENTS.md), I use a compact AGENTS.md rule so the agent automatically audits 3D coordinate files (.pdb, .cif, .mmcif) and warns about low-confidence disordered regions before running downstream structural searches or headless PyMOL renders:

# Biomolecular Structure QC Gate

Whenever a workflow downloads or modifies a 3D coordinate file (`.pdb`, `.cif`, or `.mmcif`) for downstream structural analysis, homology search, or variant mapping:

1. **Mandatory QC Audit**: Run the `structure-qc-audit` skill on the coordinate file before passing it to downstream modeling tools.
2. **Disorder Warning**: If more than 30% of alpha-carbon (`CA`) atoms have a B-factor / pLDDT score below `50.0`, explicitly warn the user about disordered or low-confidence regions and report the high-confidence domain boundaries (`pLDDT >= 70`).

Pattern 2: Zero-Pollution Python Micro-Environments (`uv` + PEP 723 + Sliding-Window PAE Math)

Running global pip install inside a user's repository breaks virtual environments. Instead, every Science skill uses uv run with PEP 723 inline script metadata (# /// script) and enforces rate limits and mathematical heuristics inside deterministic Python scripts.

For example, in skills/alphafold_database_fetch_and_analyze/scripts/:

fetch_structure.py uses polite-http with a hard qps=1.0 rate limit (CLIENT = http_client.HttpClient("https://alphafold.ebi.ac.uk", qps=1.0)) and automatically falls back to the longest isoform for massive proteins (> 2,700 amino acids like Dystrophin).
analyze_pae.py forbids the LLM from guessing domain boundaries by running a 20-residue sliding-window Predicted Aligned Error (PAE) clustering algorithm (distance_cutoff=7.0 Å, min_domain_size=40, merge_cutoff=15.0 Å):

"""Analyzes Predicted Aligned Error (PAE) and detects domain boundaries."""

# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///

def find_sub_domains(pae_matrix, distance_cutoff=7.0, min_domain_size=40):
    """Identifies structurally independent sub-domains based on the PAE matrix."""
    n_res = len(pae_matrix)
    domains, current_domain = [], []

    for i in range(n_res):
        if not current_domain:
            current_domain.append(i)
            continue

        window_size = min(20, len(current_domain))
        recent_res = current_domain[-window_size:]
        pae_sum = sum(pae_matrix[r][i] + pae_matrix[i][r] for r in recent_res)
        avg_pae = pae_sum / (2.0 * window_size)

        if avg_pae < distance_cutoff:
            current_domain.append(i)
        else:
            if len(current_domain) >= min_domain_size:
                domains.append(current_domain)
            current_domain = [i]

    if len(current_domain) >= min_domain_size:
        domains.append(current_domain)
    return [[comp[0] + 1, comp[-1] + 1] for comp in domains]

Pattern 3: The Zero-Leak Credential Protocol (`skills/credentials/SKILL.md`)

Genomic and literature APIs like AlphaGenome (ALPHAGENOME_API_KEY) require secret keys. If an agent asks a user to paste their API key into the chat - or runs cat ~/.env - that secret is permanently recorded in the conversation transcript and model context.

The credentials skill solves this with a strict Zero-Leak Protocol:

Silent Exit-Code Verification: The agent checks whether the variable exists in ~/.env using grep -sq (quiet + suppress errors), reading only the 0 vs. non-zero exit code:
```
grep -sq "^ALPHAGENOME_API_KEY=" ~/.env
```
Hidden Terminal Prompting (read -s): If missing, the agent stops immediately and outputs a terminal command for the user to run locally where keystrokes are hidden (read -s):
```
printf "Enter ALPHAGENOME_API_KEY (typing hidden): " && read -s val && echo && echo "ALPHAGENOME_API_KEY=$val" >> "$HOME/.env" && echo "Saved."
```
Internal dotenv Ingestion: Helper scripts load ~/.env internally via dotenv, so the key never appears in command-line flags or stdout.

Pattern 4: Background Sidecars (`sidecar.json`) & Custom 3D WebGL / MCP Tool Servers (`mcp_config.json`)

As documented in the public Antigravity Sidecars Guide (antigravity.google/docs/sidecars) and MCP Guide (antigravity.google/docs/mcp), Antigravity lets plugins pair Model Context Protocol (mcp_config.json) tool servers with managed background Sidecar processes (sidecar.json) that support command, builtin (schedule), args, restart_policy (always, on-failure, never), description, env, and display_name, plus programmatic interaction via agentapi.

In my open-source Antigravity Science Plugin Cookbook, I pair a zero-dependency Python Stdio MCP Server (plugins/genomics-variant-mcp/mcp_config.json) with a documented background Sidecar worker (sidecar.json) and my browser-based 3D PDBe Mol* / WebGL Biomolecular Studio (index.html):

Here are the two standard configuration files documented in antigravity.google/docs/mcp and antigravity.google/docs/sidecars:

mcp_config.json (connecting a local Stdio MCP server at the plugin root):

  {
    "mcpServers": {
      "genomics_variant_mcp": {
        "command": "uv",
        "args": ["run", "mcp/variant_mcp_server.py"],
        "timeoutSeconds": 180
      }
    }
  }

sidecars/qc_monitor/sidecar.json (configuring a managed background sidecar process per antigravity.google/docs/sidecars):

  {
    "description": "Background 3D structure QC & artifact monitor",
    "display_name": "Structure QC Sidecar",
    "command": "uv",
    "args": ["run", "worker.py"],
    "restart_policy": "on-failure"
  }

Pattern 5: Domain-Specific Guardrails - From Clinical Genetics (`AlphaGenome`) to Ancient Epigraphy (`Aeneas` & `Ithaca`)

Two of the most fascinating skills in the bundle demonstrate how SKILL.md enforces domain-specific scientific rigor:

alphagenome-variant-impact-score (Strict Molecular Framing + Context-Overflow Protection):
- Clinical Safety Gate: Explicitly forbids extrapolating high AlphaGenome Variant Impact (AVI) scores into clinical diagnoses or patient prognosis, restricting outputs to molecular mechanisms (splicing disruption, chromatin accessibility, TF binding, or GENCODE v46 transcript coordinates).
- Stdout Overflow Guard: Warns the agent that --include_track_info --format json emits ~3.9 KB per variant, requiring direct file redirection (-o query_results.json) whenever querying > 3 variants so stdout never floods the context window.
predictingthepast (Ancient Latin & Greek Epigraphy with DeepMind's Aeneas & Ithaca):
- Restores damaged ancient inscriptions, attributes geographical province + chronological date ranges, and finds parallel inscriptions using special gap syntax (? for a single missing character, # for an unknown-length damaged gap):
```
 uv run scripts/preprocess.py --language=latin --input="imp caesar divi f ???????? cos xi"
```

Enforces a Self-Contained Epigraphy Rule: forbids the agent from using web search to "cheat" or override the neural restoration probabilities returned by Aeneas/Ithaca.

4. Five End-to-End Multi-Skill Use Cases Across the 40 Science Skills

Because all 40 skills share the conversation's artifact directory, Antigravity can chain multiple domain-specific CLI scripts and MCP sidecars in a single research session.

I included a runnable benchmark suite in examples/multi_domain_science_use_cases.py (uv run examples/multi_domain_science_use_cases.py) that executes and scores all five multi-skill pipelines below:

Use Case 1: Precision Oncology & 3D Pocket Triage (`ClinVar` → `gnomAD` → `AlphaFold` → `ChEMBL` → `PyMOL / 3D WebGL Studio`)

Scenario: A translational oncology team wants to evaluate an EGFR L858R (rs121434568, chr7:55191822:T>G) driver mutation, verify gene loss-of-function constraint, inspect 3D active-site confidence, rank nanomolar kinase inhibitors, and highlight the pocket in 3D.

# 1. Check allele rarity & gene constraint (pLI / LOEUF) in gnomAD
uv run ~/.gemini/config/plugins/science/skills/gnomad_database/scripts/get_gene_constraint.py \
  --gene EGFR --output ./artifacts/egfr_constraint.json

# 2. Fetch AlphaFold 3D structure (P00533) & audit pLDDT + PAE domains
uv run ~/.gemini/config/plugins/science/skills/alphafold_database_fetch_and_analyze/scripts/fetch_structure.py \
  P00533 -o ./artifacts/P00533/
uv run ~/.gemini/config/plugins/science/skills/alphafold_database_fetch_and_analyze/scripts/analyze_pae.py \
  ./artifacts/P00533/AF-P00533-F1-predicted_aligned_error_v6.json

# 3. Screen ChEMBL for EGFR (CHEMBL203) bioactivities & download 3D SDF ligands
uv run ~/.gemini/config/plugins/science/skills/chembl_database/scripts/chembl_api.py \
  activity --search "EGFR" --limit 10 --output ./artifacts/egfr_chembl_ic50.json
uv run ~/.gemini/config/plugins/science/skills/chembl_database/scripts/chembl_api.py \
  molecule --id CHEMBL939 --dl_format sdf --output ./artifacts/gefitinib.sdf

Finally, the agent renders the 3D kinase pocket (residues 855-862 in chain A) using headless PyMOL (pymol skill) or my interactive 3D Biomolecular & Variant WebGL Studio (index.html):

Use Case 2: Non-Coding GWAS Enhancer Variant Triage (`AlphaGenome` → `UCSC phyloP` → `ENCODE cCRE` → `JASPAR` → `GTEx`)

Scenario: Over 90% of GWAS risk loci fall in non-coding DNA. Suppose you are investigating chr1:109274968:G>T (rs12740374 at the SORT1 1p13 locus) and want to know how it alters gene regulation across human tissues without hallucinating clinical diagnoses:

# 1. Score variant impact across 18 biological modalities + GENCODE v46 coordinates
uv run ~/.gemini/config/plugins/science/skills/alphagenome_variant_impact_score/scripts/alphagenome_atlas_avi.py \
  query "chr1:109274968:G>T" --include_track_info --format json -o ./artifacts/sort1_avi.json

# 2. Check 100-vertebrate evolutionary constraint (phyloP100way & phastCons100way)
uv run ~/.gemini/config/plugins/science/skills/ucsc_conservation_and_tfbs/scripts/get_conservation.py \
  --coordinates "chr1:109274968" --output ./artifacts/sort1_phylop.json

# 3. Fetch Transcription Factor Position Weight Matrices (PWMs) from JASPAR (CEBPA)
uv run ~/.gemini/config/plugins/science/skills/jaspar_database/scripts/jaspar_cli.py \
  search --query "CEBPA" --output ./artifacts/cebpa_jaspar.json

Engineering Guardrail in Action: The alphagenome-variant-impact-score skill enforces that --include_track_info outputs (~3.9 KB/variant) are redirected via -o and framed strictly in terms of molecular mechanisms (CEBPA binding site creation + liver RNA-seq eQTL shift):

Use Case 3: Dark-Proteome Enzyme Discovery (`AlphaFold` → `Foldseek 3D Search` → `InterPro` → `Clustal Omega MSA` → `Headless PyMOL`)

Scenario: A protein engineering group wants to discover novel thermostable plastic-degrading PETase homologs hidden in environmental metagenomes where sequence identity is below 25% (the "twilight zone" where BLAST fails, but 3D fold geometry is conserved):

# 1. Search the 3D coordinate file against Foldseek's metagenomic & AlphaFold databases
uv run ~/.gemini/config/plugins/science/skills/foldseek_structural_search/scripts/search.py \
  ./artifacts/PETase_AF.cif \
  --databases afdb50,mgnify_esm30,pdb100,cath50 \
  -o ./artifacts/petase_foldseek.json > ./artifacts/petase_foldseek_summary.md

# 2. Align the top structural hits with EBI Clustal Omega to verify the Ser-Asp-His catalytic triad
uv run ~/.gemini/config/plugins/science/skills/protein_sequence_msa/scripts/clustalo.py \
  --input ./artifacts/petase_homologs.fasta --output ./artifacts/petase_msa.aln

Engineering Guardrail in Action: Look at foldseek-structural-search/SKILL.md:
1. Strict Input Gate: If the user only gives a gene name or sequence without a .pdb/.cif file, the skill halts immediately and instructs the agent to fetch the 3D structure first.
2. Database Allowlist: Enforces validation against the exact 9 supported Foldseek databases (afdb50, afdb-swissprot, pdb100, BFVD, mgnify_esm30, cath50, gmgcl_id, bfmd, afdb-proteome).
3. Headless OSMesa PyMOL Superposition (pymol skill): When generating static publication figures alongside .pse session files, the pymol skill runs headless via PYOPENGL_PLATFORM=osmesa and automatically checks cmd.count_atoms("name CA") == cmd.count_atoms("all") so C-alpha-only traces still render as smooth cartoons!

Use Case 4: Clinical Trial Intelligence & Pharmacovigilance Audit (`OpenTargets` → `ClinicalTrials.gov` → `openFDA` → `OpenAlex`)

Scenario: A clinical data science team wants to map all recruiting Phase 3 trials for a target indication, inspect inclusion/exclusion criteria without overflowing the LLM context window, and audit real-world post-market adverse events across 28 FDA endpoints:

# 1. Query Open Targets for Phase 3+ candidates and target tractability
uv run ~/.gemini/config/plugins/science/skills/opentargets_database/scripts/query_opentargets.py \
  --output ./artifacts/nsclc_drugs.json --limit 15 \
  get-disease-drugs MONDO_0005090 --min-stage PHASE_3

# 2. Check total trial volume first, then fetch ONLY slimmed fields from ClinicalTrials.gov APIv2
uv run ~/.gemini/config/plugins/science/skills/clinical_trials_database/scripts/clinical_trials_api.py \
  search --condition "Non-Small Cell Lung Cancer" --status RECRUITING --phase PHASE3 \
  --count-total --fields NCTId,BriefTitle,OverallStatus,EligibilityCriteria \
  --limit 10 --output ./artifacts/nsclc_phase3_trials.json

# 3. Query openFDA Drug Adverse Events (FAERS) with automatic rate-limit protection
uv run ~/.gemini/config/plugins/science/skills/openfda_database/scripts/openfda_query.py \
  count --category drug --endpoint event \
  --search "patient.drug.medicinalproduct:osimertinib" \
  --count "patient.reaction.reactionmeddrapt.exact" \
  --limit 10 --output ./artifacts/osimertinib_faers_counts.json

Engineering Guardrails in Action:
- ClinicalTrials.gov Context Projection (--fields): Full protocolSection + resultsSection trial JSON payloads can exceed 100 KB per study. clinical-trials-database requires --count-total first and shorthand --fields projection (NCTId,BriefTitle,OverallStatus), reducing payload size by 98.7%.
- openFDA Quota Escalation (1,000 → 1 req/day): openfda-database warns that an autonomous agent can burn through the 1,000 keyless daily quota in a single session, triggering the credentials skill (grep -sq "^FDA_API_KEY=" ~/.env) before running multi-query workflows:

Use Case 5: Systems Biology & Ancient Epigraphy (`STRING` → `Reactome` & DeepMind's `Aeneas` / `Ithaca`)

Two more specialized workflows show how the Science plugin handles ambiguous biological identifiers and digital humanities:

Systems Biology Pathway Enrichment (STRING + Reactome):
- The STRING "Never Assume Human" Rule: Even if a user asks for TP53 or BRCA1 interaction partners, string-database/SKILL.md strictly forbids defaulting to Homo sapiens (9606) if the species wasn't stated - requiring the agent to ask for the NCBI Taxon ID first, map symbols via string_cli.py map, and then export pathway diagrams in reactome-database (preferring specific sub-pathways like Cell Cycle, Mitotic (R-HSA-69278) over broad top-level nodes).

Restoring Damaged Roman & Greek Stone Inscriptions (predictingthepast):

 # Preprocess damaged Latin epigraphy (? = single missing character, # = unknown-length gap)
 uv run ~/.gemini/config/plugins/science/skills/predictingthepast/scripts/preprocess.py \
   --language=latin \
   --input="imp caesar divi f ???????? cos xi trib potest"

Returns ranked character restorations (augustus, 96.4% confidence), geographical province attribution (Latium et Campania), chronological dating (23 BCE), and corpus parallels - while strictly blocking external web search so model probabilities remain unadulterated:

5. Hands-On Cookbook: Build & Run the Custom `bio-structural-qc` Plugin

In the companion repository (RobinaMirbahar/antigravity-science-plugin-cookbook), I built a complete, installable custom plugin called bio-structural-qc plus a zero-dependency 3D Protein + PAE Generator & SVG Dashboard (examples/generate_3d_protein_pae_demo.py).

Directory Structure of `bio-structural-qc`

plugins/bio-structural-qc/
├── plugin.json                                    # Manifest & 3 starter prompts
├── hooks.json                                     # PostToolUse command reproducibility hook
├── assets/
│   └── logo.svg                                   # 128x128 high-contrast SVG icon
├── rules/
│   └── AGENTS.md                                  # Mandatory QC gate before docking/Foldseek
├── scripts/
│   └── log_reproducibility_audit.py               # Redacts secrets + hashes scripts & input files
└── skills/
    └── structure-qc-audit/
        ├── SKILL.md                               # Progressive-disclosure instructions
        └── scripts/
            └── audit_structure.py                 # PEP 723 C-alpha B-factor/pLDDT auditor

1. The Always-On QC Gate (`plugins/bio-structural-qc/rules/AGENTS.md`)

# Biomolecular Structure QC Gate

Whenever a workflow downloads or modifies a 3D coordinate file (`.pdb`, `.cif`, or `.mmcif`) for downstream structural analysis, homology search, or variant mapping:

1. **Mandatory QC Audit**: Run the `structure-qc-audit` skill on the coordinate file before passing it to downstream modeling tools.
2. **Disorder Warning**: If more than 30% of alpha-carbon (`CA`) atoms have a B-factor / pLDDT score below `50.0`, explicitly warn the user about disordered or low-confidence regions and report the high-confidence domain boundaries (`pLDDT >= 70`) before rendering.

2. The Zero-Dependency PEP 723 Structure Auditor (`audit_structure.py`)

#!/usr/bin/env python3
"""Audits PDB and mmCIF coordinate files for chain completeness and B-factor/pLDDT distribution."""

# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///

import argparse, json, statistics
from pathlib import Path

def parse_ca_bfactors(filepath: Path) -> dict:
    chains: dict[str, list[tuple[int, float]]] = {}
    ext = filepath.suffix.lower()
    with filepath.open("r", encoding="utf-8", errors="replace") as f:
        for line in f:
            if ext == ".pdb" and line.startswith("ATOM  ") and line[12:16].strip() == "CA":
                chain_id = line[21].strip() or "A"
                chains.setdefault(chain_id, []).append((int(line[22:26]), float(line[60:66])))
            elif ext in {".cif", ".mmcif"} and line.startswith("ATOM "):
                parts = line.split()
                if len(parts) >= 15 and parts[3] == "CA":
                    chains.setdefault(parts[6], []).append((int(parts[8]), float(parts[14])))
    return chains

Test both the 3D generator and the QC auditor in two commands using uv run:

git clone https://github.com/RobinaMirbahar/antigravity-science-plugin-cookbook.git
cd antigravity-science-plugin-cookbook

# 1. Generate a 56-residue 3-domain 3D .pdb structure, PAE matrix JSON, and SVG dashboard
uv run examples/generate_3d_protein_pae_demo.py

# 2. Audit both the synthetic multi-domain protein and the Crambin structure
uv run plugins/bio-structural-qc/skills/structure-qc-audit/scripts/audit_structure.py \
  examples/generated_p53_demo/synthetic_p53_multidomain.pdb \
  examples/sample_crambin_fragment.pdb

Output:

[
  {
    "file": "synthetic_p53_multidomain.pdb",
    "status": "PASS",
    "total_ca_residues": 56,
    "overall_mean_score": 82.11,
    "overall_pct_low_lt_50": 17.9,
    "chains": {
      "A": {
        "residue_count": 56,
        "mean_score": 82.11,
        "median_score": 90.26,
        "pct_high_confidence_ge_70": 82.1,
        "pct_low_confidence_lt_50": 17.9,
        "high_confidence_span": [11, 56]
      }
    }
  }
]

3. Reproducibility Lifecycle Hook (`hooks.json` & `log_reproducibility_audit.py`)

A bare timestamp log only tells you when run_command fired, not what actually executed or which version of a script and input .pdb/.cif coordinates produced a scientific result. At the same time, logging raw shell commands is dangerous if an inline environment variable or --api-key flag is present.

Because Antigravity passes a structured JSON payload to every PostToolUse hook over stdin (toolCall.args.CommandLine, workspacePaths, conversationId, stepIdx), I wire plugins/bio-structural-qc/hooks.json to a zero-dependency PEP 723 audit script (plugins/bio-structural-qc/scripts/log_reproducibility_audit.py) that:

Redacts Secrets Before Logging: Strips any environment variables matching *KEY*, *TOKEN*, *SECRET*, *PASS*, *CRED*, or *AUTH*, plus Bearer/Basic headers and --api-key/--token CLI flags.
Records Exact Script Versions & Git State: Captures git rev-parse --short HEAD (+dirty if uncommitted changes exist) and computes a 16-character SHA-256 digest (script_versions) for every executed .py or .sh script.
Hashes All Referenced Input & Output Files: Tokenizes the command line and computes SHA-256 digests (file_hashes) for every referenced .pdb, .cif, .mmcif, .vcf, .json, .fasta, or .sdf file.
Honors the PostToolUse Stdout Contract: Appends the JSONL record to ~/.gemini/qc_command_audit.jsonl and emits {} on stdout.

plugins/bio-structural-qc/hooks.json:

{
  "qc-command-audit-log": {
    "enabled": true,
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          {
            "type": "command",
            "command": "uv run plugins/bio-structural-qc/scripts/log_reproducibility_audit.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

plugins/bio-structural-qc/scripts/log_reproducibility_audit.py (Core Redaction & Hashing Logic):

#!/usr/bin/env python3
"""PostToolUse reproducibility hook: logs redacted commands, script SHA-256 versions, and input file hashes."""

# /// script
# requires-python = ">=3.10"
# dependencies = []
# ///

import datetime, hashlib, json, pathlib, re, shlex, subprocess, sys

SECRET_PATTERNS = [
    (re.compile(r"\b([A-Za-z0-9_]*(?:KEY|TOKEN|SECRET|PASS|PASSWORD|CRED|AUTH)[A-Za-z0-9_]*)\s*=\s*('[^']*'|\"[^\"]*\"|\S+)", re.I), r"\1=[REDACTED]"),
    (re.compile(r"(Bearer|Basic)\s+[A-Za-z0-9._\-+/=]+", re.I), r"\1 [REDACTED]"),
    (re.compile(r"(--(?:api[-_]?key|token|secret|password)|x-goog-api-key:|api-key:)\s*([=:]?\s*)('[^']*'|\"[^\"]*\"|\S+)", re.I), r"\1\2[REDACTED]"),
]
TRACKED_EXTENSIONS = {".py", ".sh", ".pdb", ".cif", ".mmcif", ".json", ".fasta", ".fa", ".aln", ".sdf", ".vcf", ".gtf", ".tsv", ".csv"}

def redact_secrets(cmd: str) -> str:
    for pattern, repl in SECRET_PATTERNS:
        cmd = pattern.sub(repl, cmd)
    return cmd

def sha256_file(path: pathlib.Path) -> str:
    h = hashlib.sha256()
    with path.open("rb") as f:
        for chunk in iter(lambda: f.read(65536), b""):
            h.update(chunk)
    return f"sha256:{h.hexdigest()[:16]}"

Verified Commands: Test Secret Redaction & Input File Hashing Locally

You can verify both the built-in --self-test mode and the live stdin hook contract in two commands:

# 1. Run the built-in self-test (simulates an inline ALPHAGENOME_API_KEY + 2 PDB input files)
uv run plugins/bio-structural-qc/scripts/log_reproducibility_audit.py --self-test

# 2. Simulate Antigravity's PostToolUse stdin payload and inspect ~/.gemini/qc_command_audit.jsonl
printf '{"conversationId":"conv-demo","stepIdx":1,"toolCall":{"name":"run_command","args":{"CommandLine":"FDA_API_KEY=secret123 uv run plugins/bio-structural-qc/skills/structure-qc-audit/scripts/audit_structure.py examples/sample_crambin_fragment.pdb"} } }' \
  | uv run plugins/bio-structural-qc/scripts/log_reproducibility_audit.py
tail -n 1 ~/.gemini/qc_command_audit.jsonl

Verified --self-test output:

{
  "timestamp_utc": "2026-10-24T19:27:00.315004+00:00",
  "event": "PostToolUse",
  "tool": "run_command",
  "conversation_id": "conv-repro-demo-01",
  "step_idx": 7,
  "git_revision": "06fd7e9",
  "redacted_command": "ALPHAGENOME_API_KEY=[REDACTED] uv run plugins/bio-structural-qc/skills/structure-qc-audit/scripts/audit_structure.py examples/generated_p53_demo/synthetic_p53_multidomain.pdb examples/sample_crambin_fragment.pdb",
  "script_versions": {
    "plugins/bio-structural-qc/skills/structure-qc-audit/scripts/audit_structure.py": "sha256:b305f0ca720d7673"
  },
  "file_hashes": {
    "examples/generated_p53_demo/synthetic_p53_multidomain.pdb": "sha256:f929c693e8e2fbfa",
    "examples/sample_crambin_fragment.pdb": "sha256:5ddc4bb4a2f0e889"
  },
  "status": "OK"
}

4. Interactive 1-Command Plugin Scaffolder & Loader Validator (`scaffold_custom_plugin.py`)

To make authoring and testing your own plugins effortless, I also included an interactive 1-Command Plugin Scaffolder & Loader Validator (examples/scaffold_custom_plugin.py) that:

Validates any plugin directory against Antigravity's loader rules (plugin.json manifest keys, relative logo path, concise rules/AGENTS.md files, root hooks.json placement, and SKILL.md YAML frontmatter).
Scaffolds a complete new plugin bundle (plugin.json, assets/logo.svg, rules/AGENTS.md, hooks.json, SKILL.md, and a PEP 723 scripts/run_tool.py CLI script) in a single command:

# 1. Validate all 3 starter plugins in the cookbook repository
uv run examples/scaffold_custom_plugin.py

# 2. Scaffold a brand-new custom plugin bundle from scratch
uv run examples/scaffold_custom_plugin.py \
  --scaffold my-genomics-qc \
  --skill vcf-filter-audit \
  --description "Deterministic VCF quality filtering and AlphaGenome coordinate readiness checks."

# 3. Install into your global Antigravity plugins directory
cp -r plugins/bio-structural-qc ~/.gemini/config/plugins/bio-structural-qc
cp -r plugins/genomics-variant-mcp ~/.gemini/config/plugins/genomics-variant-mcp
cp -r plugins/epigraphy-citation-kit ~/.gemini/config/plugins/epigraphy-citation-kit

6. Deep Dive: The 4 Public Antigravity MCP Server Patterns + 2 More Starter Plugins (`genomics-variant-mcp` & `epigraphy-citation-kit`)

As documented in the public Antigravity MCP Guide (antigravity.google/docs/mcp), mcp_config.json supports four core server connection patterns across local developer tools and Google Cloud services:

A. The 4 Documented `mcp_config.json` Patterns

Pattern 1 - Local Stdio Subprocess (command + args + env): Spawns a local MCP process over stdio using uv, node, python3, or dart (for example, my cookbook's genomics_variant_mcp server or local SQLite/file-system explorers).
Pattern 2 - Google-Credentials Authenticated HTTP (authProviderType: "google_credentials"): Connects directly to managed Google Cloud and developer MCP endpoints (such as BigQuery, AlloyDB for PostgreSQL, Spanner, Cloud SQL, Bigtable, Dataplex, and Google Developer Knowledge at https://developerknowledge.googleapis.com/mcp) using local Application Default Credentials (gcloud auth application-default login).
Pattern 3 - Remote Streamable HTTP with Custom Headers (serverUrl + headers + timeoutSeconds): Connects to remote Streamable HTTP MCP endpoints (such as https://gemini-api-docs-mcp.dev for gemini_search_docs and gemini_get_doc) with custom Authorization headers and configurable timeouts (timeoutSeconds: 600).
Pattern 4 - OAuth 2.0 Remote Servers (Dynamic Client Registration or Manual oauth Object): Authenticates against remote SaaS and enterprise MCP servers using automatic OAuth Dynamic Client Registration (DCR) or a manual oauth (clientId, clientSecret) configuration redirecting to https://antigravity.google/oauth-callback.

B. Starter Plugin #2: `plugins/genomics-variant-mcp` (Custom Python Stdio MCP Server + Specialist Subagent)

To show how to package your own MCP server and Specialist Subagent inside an Antigravity plugin, the cookbook includes plugins/genomics-variant-mcp:

mcp_config.json - Registers genomics_variant_mcp via uv run mcp/variant_mcp_server.py and marks both tools as "eager": true so they load directly into the agent's native tool declarations:

  {
    "mcpServers": {
      "genomics_variant_mcp": {
        "command": "uv",
        "args": ["run", "mcp/variant_mcp_server.py"],
        "tools": [
          { "name": "score_variant_impact", "eager": true },
          { "name": "evaluate_lipinski_ro5", "eager": true }
        ]
      }
    }
  }

mcp/variant_mcp_server.py - A zero-dependency PEP 723 JSON-RPC 2.0 Stdio MCP server implementing initialize, tools/list, and tools/call for:
- score_variant_impact: Scores 1-based chr:pos:ref>alt SNVs (transition/transversion class, predicted AlphaGenome AVI impact score, PhyloP 100-way conservation, and molecular priority).
- evaluate_lipinski_ro5: Evaluates small-molecule leads against Lipinski's Rule of Five (MW ≤ 500, LogP ≤ 5, HBD ≤ 5, HBA ≤ 10) and Veber's polar surface area rule (PSA ≤ 140 Å²).
agents/clinical-variant-curator.md - A specialist subagent (modeled on firebase's agents/firestore-rules-author.md) with YAML frontmatter (mainAgent: true, subagent: true, commandExecutionPolicy: auto) that enforces research-only molecular framing.

Run its built-in self-test with uv:

uv run plugins/genomics-variant-mcp/mcp/variant_mcp_server.py --self-test

C. Starter Plugin #3: `plugins/epigraphy-citation-kit` (Ancient Epigraphy Validator + `PreToolUse` Hook)

The third starter plugin, plugins/epigraphy-citation-kit, pairs a PreToolUse lifecycle hook (hooks.json) with a PEP 723 Leiden bracket normalizer (validate_epigraphy.py) that automatically converts standard Leiden epigraphic brackets ([---] and [...]) into DeepMind Aeneas/Ithaca # and ? tokens, checks for forbidden ## or ?# sequences, and pads short inscriptions to the 25-character minimum:

uv run plugins/epigraphy-citation-kit/skills/epigraphy-gap-validator/scripts/validate_epigraphy.py \
  --text "IMP CAESAR DIVI F [---] COS [...] III" --language latin

7. Bonus: Distilling Live Chat Sessions into Skills & Auditing Installed Bundles

A. Automatic Skill Distillation with `workflow-skill-creator`

Don't want to write SKILL.md files from scratch? After completing any multi-step scientific workflow in chat, trigger the Science plugin's workflow-skill-creator skill:

"Package this workflow into a reusable skill."

It walks you through a mandatory 4-round brainstorming protocol (confirming inputs/outputs, error-handling rigidity, composing existing Science skills without duplicating code, and generating a CLI helper script) before writing the new skill to ~/.gemini/config/skills/<name>/.

B. Managing Plugins with `/plugin` & Auditing Installed Bundles (`inspect_installed_plugins.py`)

In Google Antigravity, you can install, enable, disable, or package plugins interactively using the built-in /plugin slash command or the Customizations -> Plugins panel in the UI.

Directory-Keyed Discovery: Antigravity resolves each installed bundle by its directory name under ~/.gemini/config/plugins/<dir>/ (or workspace .agents/plugins/<dir>/).
Zero-Context-Bloat Inventory: Never dump raw SKILL.md bodies across all installed plugins into your shell prompt. Instead, run examples/inspect_installed_plugins.py to summarize manifest versions, skill counts, active hooks.json files, mcp_config.json servers, and sidecar.json views:

# Audit the 3 cookbook plugins in ./plugins
uv run examples/inspect_installed_plugins.py

# Or audit your global Antigravity plugins directory
uv run examples/inspect_installed_plugins.py --root ~/.gemini/config/plugins

C. Installing & Inspecting Plugins from the Shell with `agy plugin`

As documented in the Antigravity Plugins Guide (antigravity.google/docs/plugins), you can install the open-source DeepMind Science skills or my cookbook plugins directly via npx or the agy plugin CLI:

# Install Google DeepMind's open-source science-skills bundle
npx skills add google-deepmind/science-skills/

# Or install and inspect plugins using the Antigravity CLI
agy plugin install https://github.com/google-deepmind/science-skills
agy plugin list --json

8. Official Documentation & Scientific Database References

A. Official Google Antigravity Documentation

B. Scientific AI Models, Databases & Open-Source Viewers

C. Licensing, Academic Citations & Dataset Acknowledgements

Google Antigravity Science Plugin License (README.md & SKILL_LICENSES.md): Copyright 2026 Google LLC. All software and helper scripts in the Science Plugin (including analyze_pae.py) are licensed under the Apache License, Version 2.0, and all skill definitions and documentation materials (including SKILL.md and rules/AGENTS.md) are licensed under the Creative Commons Attribution 4.0 International License (CC-BY 4.0). Third-party biological and clinical databases referenced by individual skills are governed by their respective terms listed in SKILL_LICENSES.md.
Google DeepMind predictingthepast (Aeneas & Ithaca) Citations:
- Aeneas (Latin): Assael, Y., Sommerschield, T., Cooley, A. et al. Contextualizing ancient texts with generative neural networks. Nature 645, 141-147 (2025). (github.com/google-deepmind/predictingthepast)
- Ithaca (Ancient Greek): Assael, Y., Sommerschield, T., Shillingford, B. et al. Restoring and attributing ancient texts using deep neural networks. Nature 603, 280-283 (2022).
Epigraphic Dataset Acknowledgements (predictingthepast):
- Ithaca (Ancient Greek): Draws on the 2019 version of the Searchable Greek Inscriptions database made available under Fair Use license by the Packard Humanities Institute, generously supported by David Packard (inscriptions.packhum.org).
- Aeneas (Latin): Trained on data from the Epigraphic Database Roma (EDR) (edr-edr.it, CC-BY 4.0 on Zenodo), the Epigraphic Database Heidelberg (EDH) (edh.ub.uni-heidelberg.de, CC-BY-SA 4.0 on Zenodo), and the ETL repository for Epigraphic Database Clauss-Slaby (EDCS_ETL) (manfredclauss.de and github.com/sdam-au/EDCS_ETL, CC-BY 4.0 on Zenodo).

Support, Star, Fork & Contribute on GitHub

If you find the Antigravity Science Plugin Cookbook & Interactive 3D WebGL Studio useful for your research or engineering workflows:

Star this Repository: Star RobinaMirbahar/antigravity-science-plugin-cookbook on GitHub to bookmark the 3 starter plugins and help other developers discover the cookbook.
Fork & Customize: Fork RobinaMirbahar/antigravity-science-plugin-cookbook to scaffold and publish your own custom Google Antigravity (@google-antigravity) plugins, progressive-disclosure skills, and MCP servers.
Play Live in Your Browser: Launch the Interactive 3D Biomolecular & Variant WebGL Studio

Official Ecosystem Links & Tags

Google: github.com/google (@google) | about.google
Google Gemini API & SDKs: github.com/google-gemini (@google-gemini) | ai.google.dev/gemini-api/docs
Google DeepMind Science & Models: github.com/google-deepmind (@google-deepmind) | deepmind.google | AlphaGenome | AlphaFold | Aeneas & Ithaca
Google Antigravity Platform: antigravity.google/docs | antigravity.google/use-cases/science | github.com/google-antigravity (@google-antigravity)
Google Cloud Platform: github.com/GoogleCloudPlatform (@GoogleCloudPlatform) | cloud.google.com

Let me know in the comments what domain you're packaging into an Antigravity plugin next - whether it's 3D structural biology, genomic variant scoring, ancient epigraphy, or autonomous cloud SRE!

Comic Studio AI: Turning Voice & Text Prompts into 4-Panel Comics with Google AI Studio, Gemini & Imagen

Robina Mirbahar — Fri, 23 Oct 2026 15:22:41 +0000

This post is my submission for DEV Education Track: Build Apps with Google AI Studio.

What I Built

As a Google Developer Expert (GDE) in AI & Cloud, one of the biggest bottlenecks I see when teaching developers and students about multimodal AI architectures is turning abstract technical concepts into engaging, visual stories.

For the Build Apps with Google AI Studio Education Track, I built Comic Studio AI, a full-stack multimodal web application generated with Google AI Studio's Build Mode, powered by Google Gemini (for structured 4-panel storyboard scripting, dialogue generation, and character consistency) and the Google Imagen API (@google/genai SDK) for rendering cohesive, high-contrast comic panels in under 60 seconds.

Key Capabilities of Comic Studio AI

🎙️ Voice or Text Idea Input: Speak or type a 1-sentence story idea or technical concept (for example, "Explain how an AI Agent uses a RAG vector database and prompt guardrails").
🧠 Structured 4-Panel Storyboard Generation (Gemini): Gemini acts as the narrative director, decomposing the raw idea into a strict JSON schema containing a shared characterBible visual anchor and 4 sequential comic panels (panelNumber, captionBanner, dialogue, and imagenPrompt).
⏸️ Optional Teacher Script-Review Gate (Human-in-the-Loop): Before spending image generation quota, educators can review and edit the 4-panel captionBanner and dialogue text while it is still JSON, ensuring technical explanations (like RAG vector retrieval) are 100% accurate before a single pixel is rendered.
🎨 Automated Multi-Panel Rendering (Imagen API): Each approved panel prompt is prepended with the shared characterBible anchor and passed to the Imagen API (imagen-4.0-generate-001 / imagen-3.0-generate-002) so character outfits, lighting, and color palettes remain consistent across all 4 panels.
📄 Selective Single-Panel Re-Roll & Export: Users can regenerate a single panel (dirtyPanelNumbers: [2]) without re-rendering the entire strip, edit speech bubbles live, and export the finished 2x2 comic strip for technical blogs, classrooms, or documentation.

Prompt Used

Here is the core structured system prompt I used inside Google AI Studio ("Build apps with Gemini") to scaffold the React + TypeScript application and wire up both Gemini and the Imagen API:

Build a responsive React + TypeScript web application called Comic Studio AI that turns a user's voice or text prompt into a 4-panel visual comic strip in under 60 seconds using Google Gemini and the Imagen API (@google/genai).

Core Requirements:

Story & Prompt Input Bar: Allow the user to enter a story topic or technical concept (via text input or browser Web Speech API voice capture), choose a visual art style (Editorial Tech Comic, Manga, Kawaii Pastel, or Superhero Ink), and toggle an optional "Review Script Before Rendering" mode for educators.

Gemini Storyboard Director (responseSchema): Call the Gemini API (gemini-2.5-flash) with structured JSON output to generate a shared characterBible string plus an array of exactly 4 panels. Each panel object must include:

panelNumber (1 to 4)

captionBanner (short narrative header)

dialogue (character speech bubble text, max 18 words)

imagenPrompt (detailed visual prompt for the Imagen API that preserves character appearance and style consistency across all 4 panels).

Human-in-the-Loop Script Review & Imagen Panel Renderer: Allow the user to inspect or edit the 4-panel script text, then call the Imagen API (imagen-4.0-generate-001) to render the 4 panel illustrations with skeleton loading states and single-panel regeneration (dirtyPanelNumbers).

Interactive 2x2 Comic Grid & Export: Render the 4 generated Imagen illustrations inside a crisp 2x2 comic book layout with bold ink borders, editable speech bubbles, and a "Download 4-Panel Comic" button.

Demo

🎥 Watch the 60-Second Live Walkthrough (YouTube)

🔗 Project Links & Source Code

💻 GitHub Repository: github.com/RobinaMirbahar/Comic-Studio-Ai
🚀 Live Showcase & Architecture Overview: Comic Studio AI (Devpost & Cloud Run Demo)

🧩 Core Gemini + Imagen Integration Architecture

Inside the generated Google AI Studio project, separating Stage 1: Narrative Scripting (Gemini) from Stage 2: Visual Synthesis (Imagen) using a strict @google/genai TypeScript Schema solves two real-world problems at once: it eliminates character drift across panels via a shared characterBible, and it lets teachers pause to review or edit the 4-panel script before rendering images:

import { GoogleGenAI, Type, Schema } from "@google/genai";

// Note: In Google AI Studio preview, GEMINI_API_KEY is injected into the sandbox environment.
// For production Cloud Run deployments, execute this module inside a server-side API route
// backed by server-side environment variables so the API key is never exposed to browser clients.
const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });

export interface ComicPanel {
  panelNumber: number;
  captionBanner: string;
  dialogue: string;
  imagenPrompt: string;
  imageUrl?: string;
}

export interface ComicStoryboard {
  characterBible: string;
  panels: ComicPanel[];
}

const comicStoryboardSchema: Schema = {
  type: Type.OBJECT,
  description: "A 4-panel comic storyboard with a shared character consistency bible.",
  properties: {
    characterBible: {
      type: Type.STRING,
      description: "Exact visual description of the recurring character (clothing, glasses, colors) prepended to every panel prompt."
    },
    panels: {
      type: Type.ARRAY,
      description: "Exactly 4 sequential comic panels.",
      items: {
        type: Type.OBJECT,
        properties: {
          panelNumber: { type: Type.INTEGER },
          captionBanner: { type: Type.STRING },
          dialogue: { type: Type.STRING },
          imagenPrompt: {
            type: Type.STRING,
            description: "Scene action, camera angle, background setting, and lighting for this specific panel."
          }
        },
        required: ["panelNumber", "captionBanner", "dialogue", "imagenPrompt"]
      }
    }
  },
  required: ["characterBible", "panels"]
};

// Stage 1: Draft the 4-panel text storyboard (allows optional human review before image rendering)
export async function draftComicStoryboard(
  idea: string,
  artStyle: string
): Promise<ComicStoryboard> {
  const storyboardResponse = await ai.models.generateContent({
    model: "gemini-2.5-flash",
    contents: `Create a 4-panel educational comic strip explaining: "${idea}". Visual style: ${artStyle}. Define a consistent characterBible and 4 sequential panels.`,
    config: {
      responseMimeType: "application/json",
      responseSchema: comicStoryboardSchema,
      temperature: 0.4
    }
  });

  const parsed: ComicStoryboard = JSON.parse(
    storyboardResponse.text || '{"characterBible":"","panels":[]}'
  );
  return {
    characterBible: parsed.characterBible,
    panels: (parsed.panels || []).slice(0, 4) // Bound to max 4 panels
  };
}

// Stage 2: Render all 4 panels (or selectively re-roll specific panel numbers) with Imagen
export async function renderApprovedPanels(
  storyboard: ComicStoryboard,
  artStyle: string,
  dirtyPanelNumbers?: number[]
): Promise<ComicPanel[]> {
  return Promise.all(
    storyboard.panels.slice(0, 4).map(async (panel) => {
      // If selective regeneration is requested, skip panels that are already approved
      if (dirtyPanelNumbers && !dirtyPanelNumbers.includes(panel.panelNumber) && panel.imageUrl) {
        return panel;
      }

      const imageResult = await ai.models.generateImages({
        model: "imagen-4.0-generate-001", // Or "imagen-3.0-generate-002"
        prompt: `${storyboard.characterBible}. ${panel.imagenPrompt}, ${artStyle} comic panel, bold ink outlines, vibrant colors`,
        config: {
          numberOfImages: 1,
          aspectRatio: "4:3",
          outputMimeType: "image/jpeg"
        }
      });

      const base64Image = imageResult.generatedImages?.[0]?.image?.imageBytes;
      return {
        ...panel,
        imageUrl: base64Image ? `data:image/jpeg;base64,${base64Image}` : ""
      };
    })
  );
}

My Experience

Working through the Build Apps with Google AI Studio Education Track highlighted three key engineering lessons that I now share in my workshops:

From Idea to Full-Stack Multimodal Prototype in Minutes: Google AI Studio's Build Mode handled all the React state management, responsive 2x2 comic grid layout, and @google/genai SDK wiring from a single structured prompt, letting me focus immediately on prompt engineering and visual consistency rather than boilerplate setup.
Structured Outputs (responseSchema) + a characterBible Anchor Solve Character Drift: When chaining text reasoning into image generation, asking Gemini to return a strict JSON schema with a top-level characterBible field and prepending that descriptor to every imagenPrompt eliminated the classic character drift problem across multi-panel comics.
Two-Stage Human-in-the-Loop Scripting Saves Quota and Improves Teaching Accuracy: Splitting storyboard generation (draftComicStoryboard) from image synthesis (renderApprovedPanels) lets educators inspect and tweak the 4-panel explanation while it is still lightweight JSON text, and re-roll individual panels without burning quota on the entire strip.

💬 Let's Connect!

Have you tried chaining Gemini Structured Outputs with the Imagen API inside Google AI Studio yet? Drop what you're building in the comments below! 👇

SlothSRE (NapOps): An Overnight Gemma 4 & ADK Agent That Compresses 418 Lines of 3 AM Alerts into a 2-Line Morning Digest

Robina Mirbahar — Wed, 21 Oct 2026 15:28:00 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

On-call software engineers lose sleep to noisy alert floods that repeat the same failure dozens of times before sunrise. When a Redis connection pool saturates during a batch job or an upstream webhook adds a new status string, alerting pipelines emit hundreds of lines of redundant stack traces across logs, CI runs, and chat channels. SlothSRE (NapOps) is an open-source, local-first overnight triage agent built with open-weights Gemma 4, Google Agent Development Kit (ADK), and Sentry Agent Tracing so engineers can sleep through 3 AM alert storms and wake up to a two-line summary with a sandbox-tested git patch ready for one-click approval.

Instead of paging a human for every retry loop, SlothSRE buffers non-critical overnight errors and runs a three-stage SequentialAgent pipeline locally on google/gemma-4-27b-it via Ollama or vLLM. In our benchmark run across 96 raw overnight alerts totaling 418 lines of stack traces and chat logs, SlothSRE collapsed the entire flood into 2 unique incident clusters (4 total summary lines), achieving a 99.04% reduction in morning reading volume and saving 42 minutes of manual log digging.

Overnight Metric	Manual 3 AM Triage	SlothSRE (NapOps) with Gemma 4
Raw Overnight Events Ingested	96 separate alerts	2 deduplicated root-cause clusters
Log & Stack-Trace Lines to Read	418 raw lines	4 summary lines (2 lines per cluster)
Log Noise Reduction	0%	99.04%
Patch Verification Before 8 AM	None (manual reproduction)	Automated local `pytest` sandbox (312.4 ms & 184.6 ms)
Morning Triage Effort	42 minutes of log correlation	1-click patch apply & PR creation

Demo

You can run the complete SlothSRE benchmark and launch the interactive FastAPI Morning Dashboard in one command from the repository:

python scripts/run_slothsre_demo.py

Running the demo executes the three-stage Gemma 4 + ADK overnight pipeline, records gen_ai.agent and gen_ai.tool spans via Sentry Agent Tracing, and verifies the live FastAPI dashboard endpoints (GET / and POST /api/approve/CLUSTER-01-REDIS-POOL):

========================================================================================
🦥 SLOTHSRE (NAPOPS) - OVERNIGHT GEMMA 4 + ADK + SENTRY TRACING REPORT
========================================================================================
  Model                  : google/gemma-4-27b-it (local Ollama / vLLM)
  Raw 3 AM Events        : 96 alerts (418 raw log lines)
  Deduplicated Clusters  : 2 clusters (4 total summary lines)
  Log Noise Reduction    : 99.04%
  Morning Time Saved     : 42 minutes
  Sentry Root Trace ID   : 0772dffd4fbfd83d5e340590efbf735e
----------------------------------------------------------------------------------------
  [1] CLUSTER-01-REDIS-POOL (billing-worker) - Collapsed 62 alerts (310 lines)
      Line 1 (What Broke)  : At 03:10 UTC, billing-worker exhausted its 10-connection Redis pool during the nightly invoice batch, triggering 62 duplicate retry alerts.
      Line 2 (Verified Fix): Gemma 4 raised max_connections to 64 with 30s health checks in redis_client.py and passed all 18 local pytest assertions in 312.4 ms.
      1-Click Command      : git apply .slothsre/patches/CLUSTER-01-REDIS-POOL.patch && gh pr create --fill
  [2] CLUSTER-02-PYDANTIC-V2-ENUM (webhook-ingest) - Collapsed 34 alerts (108 lines)
      Line 1 (What Broke)  : At 04:15 UTC, upstream payment webhooks began sending status='refund_queued', causing 34 Pydantic Literal validation rejections in webhook-ingest.
      Line 2 (Verified Fix): Gemma 4 added 'refund_queued' to WebhookEvent.status in models.py and verified schema round-trip compatibility in 184.6 ms.
      1-Click Command      : git apply .slothsre/patches/CLUSTER-02-PYDANTIC-V2-ENUM.patch && gh pr create --fill
----------------------------------------------------------------------------------------
  [FastAPI UI Verified] GET / HTTP 200 (7491 bytes)
  [1-Click Approve API] POST /api/approve/CLUSTER-01-REDIS-POOL -> {'status': 'APPROVED_AND_APPLIED', 'cluster_id': 'CLUSTER-01-REDIS-POOL', 'service_name': 'billing-worker', 'executed_command': 'git apply .slothsre/patches/CLUSTER-01-REDIS-POOL.patch && gh pr create --fill'}

To open the interactive browser dashboard on port 8095 and click the approval buttons directly (where /api/approve/{cluster_id} validates cluster_id against a strict ^CLUSTER-\d{2}-[A-Z0-9-]+$ allowlist and verifies patch.sandbox_pytest_passed == True before applying):

uvicorn slothsre_napops.app:app --host 127.0.0.1 --port 8095

Code

The full open-source implementation is available on GitHub in the slothsre_napops/ package of RobinaMirbahar/slothsre-napops:

slothsre_napops/schemas.py: Strict Pydantic v2 contracts (RawOvernightEvent, VerifiedPatchArtifact, TwoLineIncidentDigest, SentryAgentSpanRecord, and SlothMorningReport).
slothsre_napops/agent.py: Three-stage Google ADK SequentialAgent (SlothSreOvernightPipeline) wired to local open-weights Gemma 4 via LiteLlm.
slothsre_napops/sentry_tracing.py: Sentry Agent Tracing instrumentation recording gen_ai.agent and gen_ai.tool spans with input/output token counts and step durations.
slothsre_napops/app.py: FastAPI backend and Morning Coffee Digest web dashboard.
scripts/run_slothsre_demo.py: Reproducible benchmark script that generates articles/slothsre-napops/evidence/slothsre_benchmark.json.

How I Built It

SlothSRE is structured around three open-source pillars: open-weights Gemma 4 for local reasoning, Google Agent Development Kit (ADK) for deterministic multi-agent orchestration, and Sentry Agent Tracing (sentry-sdk) for observability across autonomous background steps.

1. Enforcing the Two-Line Morning Contract with Pydantic v2

To make sure the agent never replaces a 418-line log flood with a 400-word essay or hallucinates a passing test run, slothsre_napops/schemas.py enforces a strict schema where each incident cluster must resolve to line_1_what_broke, line_2_verified_fix, a one_click_command, and a VerifiedPatchArtifact cross-checked by @model_validator(mode="after"):

class TwoLineIncidentDigest(BaseModel):
    """Strict 2-line morning summary enforcing the 'Slow and Steady' anti-burnout contract."""

    cluster_id: str = Field(..., description="Deduplicated incident cluster ID.")
    service_name: str = Field(..., description="Impacted microservice.")
    raw_events_collapsed: int = Field(
        ..., description="Number of duplicate raw overnight alerts merged into this digest."
    )
    raw_lines_collapsed: int = Field(
        ..., description="Number of raw stack-trace lines compressed into 2 lines."
    )
    line_1_what_broke: str = Field(
        ..., description="Line 1: Plain-English root cause in a single sentence."
    )
    line_2_verified_fix: str = Field(
        ..., description="Line 2: Exact verified fix and test result in a single sentence."
    )
    one_click_command: str = Field(
        ..., description="Single CLI or git command to apply/merge the verified fix."
    )
    patch: VerifiedPatchArtifact = Field(..., description="Attached sandbox-verified patch.")

    @model_validator(mode="after")
    def enforce_verdict_alignment(self) -> "TwoLineIncidentDigest":
        """Prevents the LLM phrasing in Line 2 from contradicting the deterministic pytest verdict."""
        if not self.patch.sandbox_pytest_passed:
            lowered = self.line_2_verified_fix.lower()
            if "passed" in lowered or "verified" in lowered:
                raise ValueError(
                    "LLM phrasing claims verification passed, but sandbox_pytest_passed is False."
                )
        return self

2. Orchestrating Gemma 4 Locally with Google ADK SequentialAgent

In slothsre_napops/agent.py, three specialized LlmAgent stages share a local ollama/gemma4:27b endpoint through LiteLlm:

NoiseFilterAgent: Normalizes volatile memory addresses (<HEX>), request UUIDs (<UUID>), and ISO timestamps (<TS>) before computing a SHA-256 stack fingerprint, collapsing 96 raw overnight events (62 Redis pool exhaustion errors totaling 310 lines and 34 Pydantic webhook errors totaling 108 lines) into 2 unique root-cause clusters.
SandboxPatchAgent: Generates a unified git diff for services/billing_worker/redis_client.py and services/webhook_ingest/models.py, then executes pytest in a local sandbox (312.4 ms and 184.6 ms) before marking the fix ready.
TwoLineBriefAgent: Formats the verified patches into the SlothMorningReport output schema.

def build_slothsre_adk_pipeline(model_name: Optional[str] = None) -> SequentialAgent:
    """Builds the 3-stage Google ADK SequentialAgent powered by open-weights Gemma 4."""
    gemma_model = _build_local_gemma4_model(model_name)

    noise_filter_agent = LlmAgent(
        name="NoiseFilterAgent",
        model=gemma_model,
        description="Deduplicates hundreds of 3 AM stack traces, CI failures, and chat messages into unique root causes.",
        instruction=(
            "You are the SlothSRE NoiseFilterAgent running open-weights Gemma 4 locally while the human sleeps. "
            "Group duplicate stack traces and flaky retries using `deduplicate_overnight_alerts`."
        ),
        tools=[deduplicate_overnight_alerts],
        output_key="deduplicated_clusters",
    )

    sandbox_patch_agent = LlmAgent(
        name="SandboxPatchAgent",
        model=gemma_model,
        description="Drafts minimal git diffs for each overnight cluster and runs local pytest verification.",
        instruction=(
            "For each unique incident cluster in {deduplicated_clusters}, generate a minimal patch "
            "and verify it with `verify_patch_in_local_sandbox`."
        ),
        tools=[verify_patch_in_local_sandbox],
        output_key="verified_patches",
    )

    two_line_brief_agent = LlmAgent(
        name="TwoLineBriefAgent",
        model=gemma_model,
        description="Distills verified overnight patches into a strict 2-line Morning Coffee Digest.",
        instruction=(
            "Compress {verified_patches} into a SlothMorningReport where every incident has "
            "exactly 2 sentences (Line 1: What broke; Line 2: Verified fix) plus a 1-click command."
        ),
        output_schema=SlothMorningReport,
        output_key="morning_report",
    )

    return SequentialAgent(
        name="SlothSreOvernightPipeline",
        description="Sequential ADK pipeline that triages overnight alerts locally with Gemma 4.",
        sub_agents=[noise_filter_agent, sandbox_patch_agent, two_line_brief_agent],
    )

3. Instrumenting Overnight Agent Runs with Sentry Agent Tracing

When an autonomous agent runs while you are asleep, you need verifiable proof of which tools it called, how many tokens it consumed, and how long each step took. In slothsre_napops/sentry_tracing.py, SlothSentryTracer wraps each ADK agent and tool invocation in a Sentry span with gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens, and gen_ai.usage.output_tokens:

Span ID	Sentry Op	Agent / Tool Step	Input / Output Tokens	Duration (ms)
`de8105cb2e489d3e`	`gen_ai.agent`	`NoiseFilterAgent.deduplicate_overnight_alerts`	3840 / 192	412.6 ms
`482510772a320ab9`	`gen_ai.tool`	`SandboxPatchAgent.verify_patch_in_local_sandbox[CLUSTER-01-REDIS-POOL]`	620 / 148	312.4 ms
`ca536bd9739c2577`	`gen_ai.tool`	`SandboxPatchAgent.verify_patch_in_local_sandbox[CLUSTER-02-PYDANTIC-V2-ENUM]`	540 / 116	184.6 ms
`a2b713fa35fa6773`	`gen_ai.agent`	`TwoLineBriefAgent.synthesize_morning_report`	890 / 210	268.4 ms

Why Does Open Innovation Matter?

Production stack traces, local repository paths, database connection strings, and on-call chat transcripts contain sensitive infrastructure metadata that many teams cannot upload to third-party metered cloud LLM endpoints. Building SlothSRE on open-weights Gemma 4 and the open-source Google Agent Development Kit (ADK) unlocks three critical advantages that closed APIs cannot match:

Local Execution for Raw Logs and Code: Running google/gemma-4-27b-it locally via Ollama or on a private VPC-isolated Cloud Run GPU keeps every stack trace, environment variable name, and git diff inside your own machine or private network perimeter.
Zero Per-Token Anxiety During Alert Storms: A runaway retry loop at 3 AM can generate thousands of log lines in minutes. Piping an unbounded log storm into a metered commercial API risks a surprise bill before breakfast; running open-weights Gemma 4 locally incurs zero per-token API fees no matter how noisy the alert storm gets.
Offline & Local-Sandbox Determinism: Because both the model weights and the ADK SequentialAgent pipeline run locally alongside pytest, SlothSRE can test candidate patches against the local codebase without requiring external network access.

The Lazy Payoff

Before SlothSRE, reviewing an overnight batch failure meant opening four browser tabs (Cloud Run logs, GitHub Actions, Slack #oncall-sre, and local IDE search), scrolling through 418 lines of repeated tracebacks across 96 alerts, reproducing the failure locally, and writing a PR description from scratch.

With SlothSRE running on open-weights Gemma 4, those 96 noisy alerts are already collapsed into 2 two-line cards with passing pytest checks (312.4 ms and 184.6 ms) before 8:00 AM. That saves 42 minutes of manual morning triage per incident storm and lets the on-call engineer review, approve, and open both pull requests in under 30 seconds.

Prize Categories

Best Use of Gemma: Uses open-weights Gemma 4 (google/gemma-4-27b-it) via local Ollama / vLLM as the reasoning engine across all three Google ADK sub-agents (NoiseFilterAgent, SandboxPatchAgent, and TwoLineBriefAgent).
Best Use of Sentry Agent Tracing: Instruments every overnight agent step and sandbox tool call with sentry-sdk gen_ai.agent and gen_ai.tool spans (gen_ai.system, gen_ai.request.model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens) and surfaces the trace table directly in the morning dashboard.

Official Documentation & Resources

SlothSRE (NapOps) Open-Source Repository on GitHub: https://github.com/RobinaMirbahar/slothsre-napops
SlothSRE (NapOps) Core Package (slothsre_napops/): https://github.com/RobinaMirbahar/slothsre-napops/tree/main/slothsre_napops
Reproducible Benchmark Script (run_slothsre_demo.py): https://github.com/RobinaMirbahar/slothsre-napops/blob/main/scripts/run_slothsre_demo.py
Hacktoberfest Open-Source AI Challenge Week 3 (Slow and Steady): https://dev.to/challenges/hacktoberfest-week3-2026-10-19
HF26 Challenge Hub (Best Use of Gemma & Sentry Categories): https://dev.to/challenges/hf26
Google Gemma Open-Weights Models: https://cloud.google.com/vertex-ai/generative-ai/docs/open-models/use-gemma
Google Agent Development Kit (ADK) Documentation: https://google.github.io/adk-docs/
Sentry AI Agent Monitoring & Tracing Documentation: https://docs.sentry.io/product/ai-monitoring/
Ollama Local Model Runner: https://ollama.com/

Event-Driven Multi-Agent Pipelines on Google Cloud with ADK, Gemma 3 and Eventarc

Robina Mirbahar — Tue, 20 Oct 2026 03:50:56 +0000

This post is my submission for DEV Education Track: Build Multi-Agent Systems with ADK.

This article provides a step by step architectural and deployment guide for StreamForge, a real-time event-driven multi-agent pipeline built with the Google Agent Development Kit (ADK), open-weights Gemma 3 (gemma3:12b), Google Cloud Eventarc, Cloud Pub/Sub, and Google Cloud Run.

Repository: github.com/RobinaMirbahar/streamforge-event-adk

Enterprise data platforms operate on real-time state changes: a product engineering team uploads a release specification (vertex-vector-sync-v4.2.json) to a Google Cloud Storage bucket, a streaming job commits a partition to BigQuery, or a partner service publishes a schema event to Cloud Pub/Sub. Connecting Google Cloud Eventarc directly to a multi-agent Google ADK workflow runtime on Cloud Run triggers autonomous workflows within 200 ms of an object landing in storage while scaling to 0 instances when the bucket is idle.

Why Combine Eventarc with ADK `ParallelAgent` and `LoopAgent`?

Processing a multi-regional product release requires three distinct tasks: extracting technical benchmarks from the raw JSON payload, translating launch messaging across target locales (en_US, de_DE, ja_JP), and simulating 12-month Annual Recurring Revenue (ARR) expansion under regional B2B currency rules. Running those three steps sequentially increases end-to-end latency, while running them in parallel without a verification step risks publishing unrounded foreign-exchange prices.

Architecture Pattern	Trigger Mechanism	Execution Topology	Cross-Agent Consistency Check	Duplicate Event Protection
🥇 Eventarc + ADK ParallelAgent & LoopAgent	Real-time CloudEvents v1.0 (`< 200 ms` lag)	3 concurrent branches (`3x` fan-out) + LoopAgent critic	Iterative audit repairs EUR/JPY pricing until `quality_score == 1.0`	Firestore `ce-id` ledger short-circuits replays in `< 5 ms`
🥈 Scheduled ADK SequentialAgent	Fixed cron schedule	Linear 3-stage chain	Single-pass sequential handoff	Date-keyed Firestore lock
🥉 Single Monolithic Prompt	Manual human chat prompt	Single LLM call	Unchecked single-pass output	Manual retry handling

End-to-End Event-Driven Architecture on Google Cloud

Tier 1: Event Ingestion and Routing: Uploading releases/2026-10/vertex-vector-sync-v4.2.json to gs://streamforge-launch-inbox emits a native google.cloud.storage.object.v1.finalized event. Google Cloud Eventarc wraps the notification in a CNCF CloudEvents v1.0 envelope (ce-id, ce-type, ce-source, ce-time) and delivers it over an OIDC-authenticated Cloud Pub/Sub push subscription.
Tier 2: Serverless Multi-Agent Runtime (Cloud Run): A private FastAPI receiver checks the incoming ce-id header (ce-98104271-gcs-finalized) against Cloud Firestore. New events execute the Google ADK workflow (ParallelAgent → LoopAgent → LlmAgent) powered by Gemma 3 12B via LiteLlm.
Tier 3: State and Downstream Sink: The final publisher agent validates the output against the Pydantic EventDrivenLaunchManifest schema and commits both the manifest (MANIFEST-SF-VECTOR-SYNC-4.2) and the ce-id deduplication record to Cloud Firestore.

Orchestrating `ParallelAgent` Fan-Out and `LoopAgent` Self-Correction

In Google ADK, all branches inside a ParallelAgent share the same InvocationContext.session.state. Assigning a distinct output_key to each branch isolates their writes cleanly:

TechnicalSpecExtractorAgent writes engineering benchmarks to output_key="extracted_specs".
GlobalLocalizationAgent writes localized headlines and draft currency tiers to output_key="localized_copy".
RevenuePricingSimulatorAgent writes the 12-month ARR forecast and regional FX compliance rules to output_key="pricing_simulation".

Once all 3 parallel branches complete, QualityCritiqueRefinementLoop (LoopAgent with max_iterations=3) invokes LaunchReadinessCriticAgent to audit the combined state. When GlobalLocalizationAgent converts the $499/mo Growth Tier at the raw 0.92 EUR exchange rate (€459.08/mo), Iteration 1 of the LoopAgent flags the violation against the de_DE rule requiring VAT-exclusive B2B prices rounded to the nearest €5 (quality_score = 0.72) and updates the pricing tier to €460/mo. On Iteration 2, the audit reaches quality_score = 1.0 and invokes exit_quality_loop(), setting tool_context.actions.escalate = True to exit the loop immediately.

At This Point You Should Have

Python 3.10+ (3.11 recommended) with google-adk>=1.0.0, litellm, fastapi, and pydantic installed.
A Google Cloud project with Cloud Run, Eventarc, Cloud Pub/Sub, Cloud Storage, and Cloud Firestore APIs enabled.
Access to Gemma 3 12B (ollama_chat/gemma3:12b locally via Ollama or google/gemma-3-12b-it on a Cloud Run NVIDIA L4 24 GB GPU service).

Step 1: Define the CloudEvent and Launch Manifest Schemas

The pipeline enforces typed contracts at both boundaries: CloudEventEnvelope validates the incoming Eventarc HTTP headers and payload, while EventDrivenLaunchManifest constrains the final ReleasePublisherAgent output in streamforge_agent/schemas.py.

==> [1/6] Enabling Cloud Run, Eventarc, Pub/Sub, Storage, and Firestore APIs...
==> [2/6] Creating Cloud Storage Inbox Bucket & Dead-Letter Pub/Sub Topic...
==> [3/6] Creating Least-Privilege Service Accounts...
==> [4/6] Deploying StreamForge ADK Service to Cloud Run (private ingress)...
Service [streamforge-event-adk] revision [streamforge-event-adk-00001-x8k] has been deployed and is serving 100 percent of traffic.
==> [5/6] Granting Cloud Run Invoker + Eventarc EventReceiver to Eventarc SA...
==> [6/6] Creating Eventarc Trigger for google.cloud.storage.object.v1.finalized...
Created trigger [streamforge-gcs-release-trigger] in [us-central1].

Step 2: Implement the Parallel Enrichment and Loop Escalation Tools

In streamforge_agent/tools.py, each specialist tool exposes typed parameters and docstrings for Gemma 3 function calling, while exit_quality_loop sets tool_context.actions.escalate = True on the injected ADK ToolContext.

==> [1/6] Enabling Cloud Run, Eventarc, Pub/Sub, Storage, and Firestore APIs...
==> [2/6] Creating Cloud Storage Inbox Bucket & Dead-Letter Pub/Sub Topic...
==> [3/6] Creating Least-Privilege Service Accounts...
==> [4/6] Deploying StreamForge ADK Service to Cloud Run (private ingress)...
Service [streamforge-event-adk] revision [streamforge-event-adk-00001-x8k] has been deployed and is serving 100 percent of traffic.
==> [5/6] Granting Cloud Run Invoker + Eventarc EventReceiver to Eventarc SA...
==> [6/6] Creating Eventarc Trigger for google.cloud.storage.object.v1.finalized...
Created trigger [streamforge-gcs-release-trigger] in [us-central1].

Step 3: Wire `ParallelAgent`, `LoopAgent`, and `SequentialAgent`

In streamforge_agent/agent.py, build_streamforge_event_pipeline() composes the 3 parallel enrichment agents, the iterative quality critic loop, and the schema-constrained publisher agent into a single parent SequentialAgent.

==> [1/6] Enabling Cloud Run, Eventarc, Pub/Sub, Storage, and Firestore APIs...
==> [2/6] Creating Cloud Storage Inbox Bucket & Dead-Letter Pub/Sub Topic...
==> [3/6] Creating Least-Privilege Service Accounts...
==> [4/6] Deploying StreamForge ADK Service to Cloud Run (private ingress)...
Service [streamforge-event-adk] revision [streamforge-event-adk-00001-x8k] has been deployed and is serving 100 percent of traffic.
==> [5/6] Granting Cloud Run Invoker + Eventarc EventReceiver to Eventarc SA...
==> [6/6] Creating Eventarc Trigger for google.cloud.storage.object.v1.finalized...
Created trigger [streamforge-gcs-release-trigger] in [us-central1].

Step 4: Verify the Pipeline and CloudEvent Deduplication Locally

Run scripts/simulate_cloudevent_pipeline.py to execute the 3-branch ParallelAgent fan-out, inspect the 2-iteration LoopAgent self-correction trace, and verify the ce-id idempotency guard against a duplicate Pub/Sub delivery.

==> [1/6] Enabling Cloud Run, Eventarc, Pub/Sub, Storage, and Firestore APIs...
==> [2/6] Creating Cloud Storage Inbox Bucket & Dead-Letter Pub/Sub Topic...
==> [3/6] Creating Least-Privilege Service Accounts...
==> [4/6] Deploying StreamForge ADK Service to Cloud Run (private ingress)...
Service [streamforge-event-adk] revision [streamforge-event-adk-00001-x8k] has been deployed and is serving 100 percent of traffic.
==> [5/6] Granting Cloud Run Invoker + Eventarc EventReceiver to Eventarc SA...
==> [6/6] Creating Eventarc Trigger for google.cloud.storage.object.v1.finalized...
Created trigger [streamforge-gcs-release-trigger] in [us-central1].

==> [1/6] Enabling Cloud Run, Eventarc, Pub/Sub, Storage, and Firestore APIs...
==> [2/6] Creating Cloud Storage Inbox Bucket & Dead-Letter Pub/Sub Topic...
==> [3/6] Creating Least-Privilege Service Accounts...
==> [4/6] Deploying StreamForge ADK Service to Cloud Run (private ingress)...
Service [streamforge-event-adk] revision [streamforge-event-adk-00001-x8k] has been deployed and is serving 100 percent of traffic.
==> [5/6] Granting Cloud Run Invoker + Eventarc EventReceiver to Eventarc SA...
==> [6/6] Creating Eventarc Trigger for google.cloud.storage.object.v1.finalized...
Created trigger [streamforge-gcs-release-trigger] in [us-central1].

Step 5: Deploy the Private Cloud Run Receiver and Eventarc Trigger

Run deploy/deploy_eventarc_adk.sh to deploy the container to Google Cloud Run (2 vCPU, 2 GiB memory, --no-allow-unauthenticated, --min-instances=0, --max-instances=10) and bind the Eventarc trigger to google.cloud.storage.object.v1.finalized.

==> [1/6] Enabling Cloud Run, Eventarc, Pub/Sub, Storage, and Firestore APIs...
==> [2/6] Creating Cloud Storage Inbox Bucket & Dead-Letter Pub/Sub Topic...
==> [3/6] Creating Least-Privilege Service Accounts...
==> [4/6] Deploying StreamForge ADK Service to Cloud Run (private ingress)...
Service [streamforge-event-adk] revision [streamforge-event-adk-00001-x8k] has been deployed and is serving 100 percent of traffic.
==> [5/6] Granting Cloud Run Invoker + Eventarc EventReceiver to Eventarc SA...
==> [6/6] Creating Eventarc Trigger for google.cloud.storage.object.v1.finalized...
Created trigger [streamforge-gcs-release-trigger] in [us-central1].

==> [1/6] Enabling Cloud Run, Eventarc, Pub/Sub, Storage, and Firestore APIs...
==> [2/6] Creating Cloud Storage Inbox Bucket & Dead-Letter Pub/Sub Topic...
==> [3/6] Creating Least-Privilege Service Accounts...
==> [4/6] Deploying StreamForge ADK Service to Cloud Run (private ingress)...
Service [streamforge-event-adk] revision [streamforge-event-adk-00001-x8k] has been deployed and is serving 100 percent of traffic.
==> [5/6] Granting Cloud Run Invoker + Eventarc EventReceiver to Eventarc SA...
==> [6/6] Creating Eventarc Trigger for google.cloud.storage.object.v1.finalized...
Created trigger [streamforge-gcs-release-trigger] in [us-central1].

Official Google Cloud and ADK Documentation

Summary

The goal of this article was to build and verify a real-time, event-driven multi-agent pipeline on Google Cloud using Eventarc, Cloud Pub/Sub, Cloud Run, open-weights Gemma 3, and the Google Agent Development Kit. The key to the solution was pairing ParallelAgent for concurrent 3-branch fan-out with LoopAgent for iterative cross-branch self-correction and a Cloud Firestore ce-id deduplication ledger. The verification results were:

🟢 Concurrent Fan-Out (ParallelAgent): Extracted engineering specs (73.8% latency drop from 145 ms to 38 ms at 250,000 rows/sec), localized copy across 3 locales (en_US, de_DE, ja_JP), and forecasted $2,856,000 in 12-month Net New ARR lift across 340 upgraded accounts (18.5% of 1,840 active Growth Tier accounts at $8,400 annual expansion).
🟢 Self-Correcting Quality Loop (LoopAgent): Detected the €459.08/mo and ¥75,848/mo currency formatting violations on Iteration 1 (quality_score = 0.72), repaired them to €460/mo and ¥75,800/mo, and exited cleanly on Iteration 2 (quality_score = 1.0) via exit_quality_loop().
🟢 At-Least-Once Idempotency: Short-circuited duplicate ce-98104271-gcs-finalized redelivery in < 5 ms with 0 redundant parallel branches or LLM calls.

The strategy for orchestrating event-driven multi-agent pipelines with Google ADK and Gemma 3 on Cloud Run was validated with an incremental step by step approach.

Building Production-Ready Open-Weights AI Agents with Gemma, Google ADK, and Cloud Run GPUs

Robina Mirbahar — Fri, 16 Oct 2026 16:43:29 +0000

Figure 1: The four foundational pillars I used to take an open-weights Gemma agent from a local prototype to governed enterprise production on Google Cloud.

Most AI tutorials stop at a basic "Hello World" chatbot running on a laptop. However, when engineering teams try to move open-weights models like Google’s Gemma 3 (gemma-3-4b-it, gemma-3-12b-it, gemma-3-27b-it) into real enterprise production, they immediately hit four hard engineering questions:

Grounding: How do I connect Gemma to live enterprise data (like Cloud Firestore) so it doesn't hallucinate?
Serverless GPU Scaling: How do I serve Gemma on GPUs (Cloud Run + vLLM + Cloud Storage FUSE) so it scales to zero when idle instead of burning thousands of dollars a month?
Reliability & Governance: How do I guarantee the agent cannot pass malformed tool parameters or accidentally take down a production service?
Testing & Optimization: How do I unit-test an AI agent's tool calls in CI/CD, and how do I fine-tune a small, fast Gemma 4B model with LoRA on Vertex AI so it performs like a 27B model?

I wrote this article to serve as a complete, end-to-end Enterprise Reference Blueprint that answers all four questions using a single, working project (CloudGuard) verified in Google Cloud Shell (all working code is available in my cloudguard-gemma-agent GitHub repository).

Where This Blueprint Is Useful in Production

DevOps, SRE & Automated Incident Response: On-call engineers often waste 20-30 minutes during an outage manually querying logs, searching old postmortems, and finding remediation runbooks. CloudGuard automatically pulls live incident telemetry from Cloud Firestore (get_service_incident), matches symptoms against historical postmortems in its Long-Term Memory Bank (MEM-2026-014), and executes approved mitigations in staging (mitigate_runaway_workload).
Cloud FinOps & GPU Quota Governance: A single misconfigured ML batch job or unthrottled retry loop can spin up dozens of GPUs overnight. CloudGuard checks real-time regional GPU utilization (NVIDIA L4 and RTX PRO 6000) and monthly budget burn (check_gpu_quota_and_cost), immediately scaling down runaway staging workloads and calculating hourly dollar savings ($36.12/hr).
Regulated Enterprises Requiring Data Sovereignty (Banking, Healthcare, Government, FinOps): Organizations prohibited from sending application telemetry logs, credentials, or infrastructure schemas to external third-party APIs can deploy open-weights Gemma inside their own Google Cloud project behind --no-allow-unauthenticated service and Model Armor guardrails (cloudguard_agent/guardrails.py), where accidentally pasted GCP API keys (AIza...) are redacted before reaching the model.
AI Engineering & MLOps CI/CD Pipelines: Instead of relying on manual "vibe checks" when prompts or tools change, my ADK Eval harness (scripts/run_eval.py) scores Tool Trajectory Accuracy (1.00) and Response Factuality (1.00) on every build, while my Vertex AI QLoRA pipeline (scripts/prepare_and_verify_lora.py) lets teams replace a 54 GB VRAM model (Gemma 27B) with an 8.9 GB VRAM model (Gemma 4B + LoRA) running in ~51ms on a single NVIDIA L4 GPU.

Here are the six stages of the production lifecycle I will walk through:

Build: Scaffolding a model-agnostic Google ADK agent in Python that runs against local Gemma weights (via Ollama) during development and seamlessly switches to Cloud Run GPUs or Vertex AI Model Garden in production.
Connect: Authoring native Python function-calling tools backed by Cloud Firestore to inspect live production incidents and regional GPU FinOps quotas.
Scale: Deploying vLLM on Cloud Run Serverless GPUs (NVIDIA L4 / RTX PRO 6000) with Cloud Storage FUSE for zero-download weight streaming, paired with Short-Term Session State and a Long-Term Memory Bank.
Govern: Enforcing deterministic parameter validation with private Cloud Run service configurations, Model Armor parameter formatting (before_model_callback), and deterministic RBAC tool policies (before_tool_callback).
Optimize: Automating CI/CD release gates with ADK Eval (tool_trajectory_avg_score and response_match_score) and OpenTelemetry tracing for Google Cloud Trace.
Specialize: Fine-tuning a compact google/gemma-3-4b-it model using QLoRA on Vertex AI so it matches gemma-3-27b-it tool-calling accuracy (1.00) at 2.8x faster latency and 6x lower GPU memory.

Figure 2: End-to-end request lifecycle for my CloudGuard Incident & FinOps Agent across Cloud Run, vLLM, Cloud Firestore, Model Armor guardrails, and Cloud Trace.

Part 1: Platform Foundations & Scaffolding the First Gemma Agent

Prerequisites & Google Cloud Setup

To follow along with my setup, you will need:

A Google Cloud Project with billing enabled.
The Google Cloud SDK (gcloud) installed and authenticated.
Python 3.10+ and uv (the fast Python package and virtual environment manager I use across this project).
Ollama installed locally (ollama pull gemma3:4b or ollama pull gemma3:27b) for zero-cost local prototyping before deploying to Google Cloud GPUs.

First, I set my project and region environment variables and enabled the required Google Cloud APIs:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Next, I configured Application Default Credentials (ADC) so my local Python environment can authenticate with Google Cloud services:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Scaffolding the Project (Local or 1-Click in Google Cloud Shell)

You can either clone and run this project directly inside Google Cloud Shell (which comes pre-authenticated with gcloud and Python in your browser) by clicking Open in Google Cloud Shell, or initialize the workspace locally with uv:

Step 1: Launching the RobinaMirbahar/cloudguard-gemma-agent repository directly inside Google Cloud Shell.

Step 2: Authorizing Google Cloud Shell credentials while the repository clones into the Cloud Shell workspace.

Step 3: Executing the CloudGuard environment setup, database seeding, and ADK evaluation commands inside the Google Cloud Shell terminal.

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

I structured the repository so that agent orchestration, native tools, memory management, validation callbacks, and evaluation suites are cleanly separated (and runnable offline via a deterministic local simulation harness before touching cloud GPUs):

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Repository structure of RobinaMirbahar/cloudguard-gemma-agent showing the modular separation across agent orchestration, Firestore tools, memory, guardrails, deployment manifests, and evaluation scripts.

In pyproject.toml, I declared google-adk, litellm, google-cloud-firestore, and opentelemetry-sdk:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Then I locked and installed the dependencies:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Decoupling Local vs. Cloud GPU Inference (`.env.example`)

One of the strongest architectural benefits of Google ADK is its model-agnostic LiteLlm integration. By defining a .env configuration file, I can point my agent to a local Ollama server on localhost:11434 during development and switch to a self-hosted vLLM endpoint on Cloud Run GPUs (or Vertex AI Model Garden) in production without changing a single line of agent orchestration code:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Defining the CloudGuard Agent Persona (`cloudguard_agent/agent.py`)

When building agents with open-weights models like Gemma, explicit, numbered system instructions are essential. Here is how I defined the agent's identity, tool bindings, and strict operational constraints in cloudguard_agent/agent.py:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Part 2: Native Python Tools & Connecting to Cloud Firestore

Figure 3: How Google ADK introspects my Python type hints and docstrings to drive structured Gemma tool calls against Cloud Firestore.

An isolated LLM knows nothing about active Cloud Run services, operational SRE runbooks, or current monthly GPU FinOps burn rates. To bridge that gap, Google ADK automatically converts standard Python functions into JSON Schema tool definitions for Gemma.

My Engineering Rule for Open-Weights Gemma: Compact open-weights models (Gemma 4B, 12B, 27B) rely heavily on explicit Args: descriptions and concrete format examples (such as 'INC-YYYY-NNNN') in Python docstrings to construct valid JSON tool arguments. I treat Python docstrings as first-class prompt engineering.

Implementing the Operational Tools (`cloudguard_agent/tools.py`)

I built four native Python tools backed by Cloud Firestore (plus a zero-config local JSON schema mirror (USE_LOCAL_MOCK_DB="true") so the entire test suite can be verified locally before provisioning cloud resources):

get_service_incident(incident_id: str): Retrieves severity, symptom, GPU type, hourly USD burn rate, and remediation runbook for a specific incident ticket.
list_active_alerts(environment: str = "all"): Lists open incidents filtered by production, staging, or all.
check_gpu_quota_and_cost(region: str): Checks regional NVIDIA L4 and RTX PRO 6000 quota limits, active usage, and monthly FinOps budget percentage.
mitigate_runaway_workload(...): Scales down a runaway Cloud Run service or batch job and records the hourly cost savings.

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Seeding the Database (`scripts/seed_firestore.py`)

When connecting to a live Cloud Firestore instance in Google Cloud, you can provision the database in Native mode:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

I then ran scripts/seed_firestore.py to populate the incidents and quotas collections:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Here is the terminal output from running the database seeder:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Running scripts/seed_firestore.py inside Google Cloud Shell to populate the incidents and quotas collections.

Part 3: Scaling with Cloud Run Serverless GPUs, Vertex AI Model Garden & Dual Memory

Figure 4: Streaming Gemma weights from Cloud Storage FUSE into Cloud Run Serverless GPUs with vLLM, backed by Short-Term Session State and a Long-Term Enterprise Memory Bank.

Moving an open-weights Gemma model from a developer laptop into enterprise production on Google Cloud offers two primary deployment patterns: Cloud Run Serverless GPUs with vLLM (for scale-to-zero serverless containers) or Vertex AI Model Garden (for one-call managed GPU endpoints).

Option A: Serverless GPU Serving on Cloud Run with vLLM & Cloud Storage FUSE

Instead of baking multi-gigabyte model weights into a container image - or downloading them from Hugging Face on every cold start - I stage the Gemma weights in a regional Google Cloud Storage (GCS) bucket and mount that bucket at /mnt/models using Cloud Storage FUSE.

VRAM Sizing Note on Google Cloud Run GPUs: A single NVIDIA L4 GPU on Cloud Run provides 24 GB of VRAM, which easily fits google/gemma-3-4b-it (~8.4 GB in bfloat16), google/gemma-3-12b-it, or a 4-bit AWQ quantized google/gemma-3-27b-it. To run unquantized bfloat16 google/gemma-3-27b-it (~54 GB VRAM) on a single serverless instance, use --gpu-type=nvidia-rtx-pro-6000 on Cloud Run or deploy on Vertex AI Model Garden.

Here is my deploy/Dockerfile.vllm configuration:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

And here is the gcloud run deploy command from deploy/deploy_cloud_run_gpu.sh mounting the GCS FUSE volume:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Option B: Managed Deployment via Vertex AI Model Garden

Alternatively, if you prefer a managed endpoint provisioned directly from Vertex AI Model Garden, you can deploy google/gemma3@gemma-3-4b-it or google/gemma3@gemma-3-27b-it programmatically using the Vertex AI Python SDK:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Dual-Tier Memory: Short-Term Session State vs. Long-Term Memory Bank

In cloudguard_agent/memory.py, I equipped the agent with two distinct memory layers:

Short-Term Conversational Session (AgentSessionState): Tracks the active incident ID (active_incident_id) within the current troubleshooting thread. When an engineer inspects INC-2026-0891 in Turn 2 and says "Go ahead and mitigate that runaway staging workload" in Turn 4, the agent resolves the reference automatically.
Long-Term Organizational Memory (EnterpriseMemoryBank): Stores verified postmortem learnings across all sessions. When INC-2026-0891 triggers on ml-batch-indexer-dev, the agent automatically searches historical postmortems and retrieves MEM-2026-014.

Here is the execution output from running my multi-turn simulation harness (uv run python scripts/simulate_parts.py):

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Live execution of scripts/simulate_parts.py in Google Cloud Shell showing multi-turn tool calling, Long-Term Memory Bank matching (MEM-2026-014), and Short-Term Session State mitigation.

Part 4: Deterministic Input Formatting & Tool Parameter Validation

Figure 5: Three sequential validation gates I implemented to protect the CloudGuard agent: Cloud Run service routing, Before-Model parameter formatting & injection blocking, and Before-Tool RBAC enforcement.

Giving an AI agent write-access to infrastructure requires deterministic validation boundaries. Telling an LLM "Never scale down production" inside a system prompt is a probabilistic guideline - not an enterprise reliability control.

I implemented defense-in-depth across three sequential gates:

Gate 1: Service-to-Service Cloud Run Routing: The gemma-vllm-service is configured with --no-allow-unauthenticated. Only the ADK orchestrator's service account (cloudguard-agent-sa) holds roles/run.invoker permission.
Gate 2: Before-Model Input Sanitization (inspect_and_sanitize_prompt): Modeled on Google Cloud Model Armor, this interceptor scans every incoming prompt for adversarial jailbreak signatures and automatically redacts live credentials (such as AIza... GCP API keys or ya29... bearer tokens) before they reach the Gemma model or telemetry logs.
Gate 3: Before-Tool Deterministic RBAC (validate_tool_invocation): Intercepts every mitigate_runaway_workload call before Python executes it, blocking any production mutation unless the caller holds sre-incident-commander privileges (POL-PROD-MUTATION-001).

Guardrail Implementation (`cloudguard_agent/guardrails.py`)

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Validation Verification Output

Here is the audit trace from testing invalid parameter formatting, unauthorized production scaling, and prompt injection against my guardrails:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Live execution of scripts/simulate_parts.py in Google Cloud Shell verifying live API key redaction ([REDACTED_GCP_API_KEY]), RBAC production scaling denial (POL-PROD-MUTATION-001), and Model Armor prompt injection blocking.

Part 5: Observability & Deterministic Evaluation (ADK Eval)

Figure 6: Automated CI/CD evaluation pipeline scoring both Tool Trajectory Accuracy and Response Factuality while exporting OpenTelemetry spans to Google Cloud Trace.

Manual "vibe checks" in a chat UI cannot prevent regressions when prompts, tools, or model weights change. Following ADK Eval best practices, I built scripts/run_eval.py to evaluate the agent against a golden dataset (tests/eval_dataset.json) across two quantitative metrics:

Tool Trajectory Score (tool_trajectory_avg_score): Verifies that the agent invoked the exact expected sequence of tools with the exact expected JSON arguments (1.00 = 100% match).
Response Factuality Score (response_match_score): Verifies that required domain identifiers (Incident IDs, runbook codes, dollar savings, or RBAC policy codes) appear in the synthesized response.

Running uv run python scripts/run_eval.py produces the following evaluation table and Google Cloud Trace OpenTelemetry span:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Executing scripts/run_eval.py in Google Cloud Shell: 5/5 golden test cases passing with a 1.00 Tool Trajectory score and exported OpenTelemetry `gen_ai.` span.*

Part 6: Fine-Tuning Gemma with QLoRA on Vertex AI for Domain Tool Calling

Figure 7: End-to-end domain specialization lifecycle - converting verified production traces into a Gemma SFT dataset, training a QLoRA adapter on Vertex AI, and hot-loading it into Cloud Run vLLM.

While google/gemma-3-27b-it achieves a 1.00 tool-trajectory score out of the box, unquantized bfloat16 weights require ~54 GB of VRAM. To run cleanly on a single 24 GB NVIDIA L4 GPU on Cloud Run with plenty of room for concurrent KV-cache requests, I wanted to specialize the compact google/gemma-3-4b-it model (which uses only 8.9 GB of VRAM and responds in ~51ms).

Using cloudguard_agent/finetuning.py (uv run python scripts/prepare_and_verify_lora.py), I exported verified multi-turn tool trajectories into Gemma's official <start_of_turn> SFT format (data/cloudguard_gemma_sft_train.jsonl) and generated the Vertex AI Custom Training (NVIDIA_L4 QLoRA r=16, lora_alpha=32) specification:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Live execution in Google Cloud Shell exporting golden SFT trajectories formatted with Gemma's <start_of_turn> and tool_code tokens.

Once Vertex AI writes the LoRA adapter weights to gs://${PROJECT_ID}-gemma-weights/adapters/cloudguard-sre-lora-v1, I hot-load the adapter into vLLM on Cloud Run (--enable-lora --lora-modules cloudguard-sre-lora-v1=/mnt/models/adapters/cloudguard-sre-lora-v1).

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Live execution inside Google Cloud Shell generating the Vertex AI NVIDIA_L4 QLoRA job specification and verifying the post-tuning ADK Eval benchmark.

With domain QLoRA fine-tuning, the compact Gemma 4B model matches the 1.00 Tool Trajectory score of the 27B model while cutting latency from 144.1ms down to 51.4ms and fitting effortlessly on a single Cloud Run NVIDIA L4 GPU.

Cleaning Up Cloud Resources (FinOps Hygiene)

If you deploy the Cloud Run GPU services and GCS bucket in your own Google Cloud project, remember to tear them down when finished experimenting:

export PROJECT_ID=$(gcloud config get-value project)
export REGION="us-central1"

gcloud run services delete cloudguard-adk-agent --region=${REGION} --quiet
gcloud run services delete gemma-vllm-service --region=${REGION} --quiet
gcloud storage rm --recursive gs://${PROJECT_ID}-gemma-weights

Key Takeaways

Open-Weights Control + Cloud-Native Speed: Pairing Gemma 3 with Google ADK gives me complete model weight ownership and VPC data residency without sacrificing developer velocity.
Serverless GPU Economics: Combining vLLM, Cloud Run Serverless GPUs (nvidia-l4), and Cloud Storage FUSE eliminates both idle GPU VM waste and slow container cold starts.
Deterministic Governance & Evaluation: Using before_model_callback, before_tool_callback, and ADK Eval turns probabilistic LLM agents into auditable, production-grade software systems.

Companion GitHub Repository

All source code, Dockerfiles, Cloud Run Serverless GPU deployment manifests, golden evaluation datasets, and Vertex AI QLoRA fine-tuning scripts from my tutorial are open-source and available on GitHub:

GitHub Repository: github.com/RobinaMirbahar/cloudguard-gemma-agent
Core Agent & Orchestrator: cloudguard_agent/agent.py
Native Firestore & FinOps Tools: cloudguard_agent/tools.py
Input & Tool Parameter Validators: cloudguard_agent/guardrails.py
ADK Eval & OpenTelemetry Runner: scripts/run_eval.py
Vertex AI QLoRA Fine-Tuning: cloudguard_agent/finetuning.py

Official Google Cloud Documentation & References

Google Gemma Open Models Overview: ai.google.dev/gemma
Google Agent Development Kit (ADK) Documentation: google.github.io/adk-docs
Deploying Gemma on Vertex AI Model Garden: cloud.google.com/vertex-ai/generative-ai/docs/open-models/use-gemma
Cloud Run Serverless GPUs Documentation: cloud.google.com/run/docs/configuring/services/gpu
Cloud Storage FUSE Volume Mounts on Cloud Run: cloud.google.com/run/docs/configuring/services/cloud-storage-volume-mounts
Cloud Firestore Native Mode Documentation: cloud.google.com/firestore/docs
Google Cloud Run Documentation: cloud.google.com/run/docs
ADK Deterministic Agent Evaluation (ADK Eval): google.github.io/adk-docs/evaluate
Google Cloud Trace & OpenTelemetry for Python: cloud.google.com/trace/docs/setup/python-ot
Gemma Chat & Function Calling Formatting (<start_of_turn>): ai.google.dev/gemma/docs/formatting

Architecting Autonomous Lakehouse Agents: Governed Iceberg Analytics with Gemini 2.5 Flash and BigLake

Robina Mirbahar — Thu, 15 Oct 2026 15:57:55 +0000

The decoupling of compute from storage has positioned Apache Iceberg as the de facto open table format across enterprise cloud data architectures. By providing ACID transactions, schema evolution without rewriting data files, hidden partitioning, and time-travel snapshots, Iceberg enables organizations to store petabytes of analytical data in Google Cloud Storage (GCS) while querying it via heterogeneous engines.

However, bridging autonomous Large Language Model (LLM) agents with production Iceberg lakehouses creates severe architectural challenges:

Financial Denial-of-Service (FDOS) & Runaway Queries: In a lakehouse with 50+ TB tables, an unconstrained LLM generating an unpartitioned SELECT * or multi-way cross-join will trigger multi-hundred-dollar scanning fees in seconds.
Dynamic Schema Drift & Partition Transform Hallucinations: Apache Iceberg separates logical table schemas from physical partition specs (identity, year, month, bucket[N], truncate[W]). Traditional static prompt engineering inevitably causes models to hallucinate non-existent partition columns or miss partition pruning entirely.
Destructive Mutation Risks: Semantic misinterpretations can cause models to emit non-idempotent or destructive DDL/DML statements (DROP, DELETE, TRUNCATE, ALTER).

To solve these problems, I architected and built an end-to-end, production-grade Autonomous Data Agent using Google’s Agent Development Kit (ADK) design patterns, Gemini 2.5 Flash, BigLake Iceberg REST Catalogs, and Abstract Syntax Tree (AST) guardrails. In this article, I will walk you through how I designed and implemented this system.

🏛️ System Architecture Topology

In my architecture, the agent never directly touches physical data files or executes raw, unvetted SQL against storage engines. Instead, I designed it to operate inside a closed-loop, deterministic execution framework structured across three distinct tiers:

                            User Natural Language Query
                                       │
                                       ▼
                     ┌───────────────────────────────────┐
                     │    Gemini 2.5 Flash Orchestrator   │
                     │  (Temperature: 0.0, Seed-Locked)  │
                     └─────────────────┬─────────────────┘
                                       │
                ┌──────────────────────┴──────────────────────┐
                │                                             │
                ▼                                             ▼
    ┌──────────────────────┐                     ┌─────────────────────────┐
    │ Tier 1: Discovery    │                     │ Tier 2: Validation      │
    │ Iceberg REST Catalog │                     │ AST Read-Only Check     │
    │ Partition Layouts    │                     │ BigQuery Zero-Cost Dry  │
    │ Active Snapshots     │                     │ Scan Budget Gate (<500M)│
    └──────────┬───────────┘                     └────────────┬────────────┘
               │                                              │
               │ [Validated AST + Estimated Cost Passed]     │
               └──────────────────────┬───────────────────────┘
                                      │
                                      ▼
                        ┌───────────────────────────┐
                        │ Tier 3: Vectorized Engine │
                        │ BigQuery Native Vectorized│
                        │ Parquet Pushdown via GCS  │
                        └─────────────┬─────────────┘
                                      │
                                      ▼
                        Bounded Result Dataframe
                                      │
                                      ▼
                      Synthesized Analytical Response

The Three Operational Tiers:

Tier 1: Deep Lakehouse Metadata & Partition Probing: The agent inspects the BigLake Iceberg REST Catalog at runtime to dynamically inspect the active schema, column types, clustering keys, and physical partition transforms.
Tier 2: Static AST Analysis & Zero-Cost Dry-Run Guardrails: The generated SQL undergoes Abstract Syntax Tree (AST) token parsing via SQLGlot to ensure read-only immutability. It is then compiled through BigQuery’s zero-cost dry-run API to enforce an absolute byte scanning budget (<500 MB).
Tier 3: Governed Vectorized Read Execution: The approved query is executed using BigLake's vectorized Parquet reader directly over Cloud Storage, returning a strictly bounded result payload.

📦 Environment Setup & Dependencies

Ensure your execution environment has the required Google Cloud and parsing dependencies installed:

pip install google-genai google-cloud-bigquery sqlglot pydantic

import os
import json
from typing import Dict, Any, List, Optional
from pydantic import BaseModel, Field
import sqlglot
from sqlglot import exp
from google import genai
from google.genai import types
from google.cloud import bigquery
from google.cloud.exceptions import GoogleCloudError

# Configuration & Runtime Limits
PROJECT_ID = os.environ.get("GCP_PROJECT_ID", "enterprise-lakehouse-prod")
LOCATION = os.environ.get("GCP_REGION", "us-central1")
MAX_SCAN_LIMIT_BYTES = 500 * 1024 * 1024  # Strict 500 MB Safety Ceiling

# Initialize Clients
bq_client = bigquery.Client(project=PROJECT_ID, location=LOCATION)
ai_client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

🔧 Tier 1: Iceberg REST Catalog & Metadata Discovery Tool

Passing static schemas inside system prompts fails because modern Iceberg tables continuously evolve. To solve this, I built a metadata discovery tool that allows my agent to inspect table schemas, field constraints, partitioning strategies, and clustering keys dynamically at runtime:

class ColumnDefinition(BaseModel):
    name: str
    data_type: str
    mode: str
    description: Optional[str] = None

class TableMetadataResponse(BaseModel):
    table_id: str
    table_type: str
    columns: List[ColumnDefinition]
    partition_specs: List[str]
    clustering_keys: List[str]

def get_lakehouse_table_schema(dataset_id: str, table_id: str) -> str:
    """
    Queries the BigLake Iceberg REST Catalog to extract dynamic table schema,
    column types, partition transformations, and clustering configurations.
    """
    full_table_path = f"{PROJECT_ID}.{dataset_id}.{table_id}"
    try:
        table = bq_client.get_table(full_table_path)
    except GoogleCloudError as e:
        return f"ERROR: Failed to resolve table '{full_table_path}': {str(e)}"

    columns = []
    for field in table.schema:
        columns.append(
            ColumnDefinition(
                name=field.name,
                data_type=field.field_type,
                mode=field.mode,
                description=field.description or "No description provided"
            )
        )

    partition_specs = []
    if table.time_partitioning:
        partition_specs.append(
            f"Time Partition Field: '{table.time_partitioning.field}' "
            f"(Type: {table.time_partitioning.type_})"
        )
    if table.range_partitioning:
        partition_specs.append(
            f"Range Partition Field: '{table.range_partitioning.field}'"
        )

    clustering_keys = table.clustering_fields if table.clustering_fields else []

    metadata = TableMetadataResponse(
        table_id=full_table_path,
        table_type=table.table_type,
        columns=columns,
        partition_specs=partition_specs,
        clustering_keys=clustering_keys
    )

    return metadata.model_dump_json(indent=2)

🛡️ Tier 2: AST Read-Only Validation & BigQuery Dry-Run Guardrails

To prevent accidental multi-terabyte full-table scans, I implemented a validation gate that runs two sequential read-only and cost layers before any query can touch the lakehouse:

AST Token Traversal: Disallows all non-SELECT queries, subquery mutations, and administrative commands using sqlglot.
Zero-Cost Dry Run: Pre-compiles the query on Google Cloud to calculate the exact total_bytes_processed before billing occurs.

def audit_and_estimate_sql_cost(sql_statement: str) -> str:
    """
    Performs Abstract Syntax Tree (AST) validation and a zero-cost BigQuery dry-run.
    Enforces a strict 500MB scan ceiling and blocks all non-SELECT DDL/DML statements.
    """
    # -------------------------------------------------------------
    # Layer 1: Abstract Syntax Tree (AST) Immutability Check
    # -------------------------------------------------------------
    try:
        parsed_tree = sqlglot.parse_one(sql_statement, read="bigquery")
    except Exception as parse_err:
        return json.dumps({
            "status": "REJECTED",
            "reason": f"SQL Syntax/Parsing Error: {str(parse_err)}"
        })

    # Ensure the root expression is strictly a SELECT or UNION
    if not isinstance(parsed_tree, (exp.Select, exp.Union)):
        return json.dumps({
            "status": "REJECTED",
            "reason": "Root statement must be a read-only SELECT or UNION query."
        })

    # Disallow destructive or mutating expressions anywhere in the AST
    forbidden_ast_nodes = (
        exp.Drop, exp.Delete, exp.TruncateTable, exp.Insert,
        exp.Update, exp.AlterTable, exp.Command, exp.Merge
    )
    for node in parsed_tree.walk():
        if isinstance(node, forbidden_ast_nodes):
            return json.dumps({
                "status": "REJECTED",
                "reason": f"Forbidden mutation expression detected: {node.key.upper()}"
            })

    # -------------------------------------------------------------
    # Layer 2: BigQuery Dry-Run Scan Evaluation (Zero-Cost Metric)
    # -------------------------------------------------------------
    job_config = bigquery.QueryJobConfig(
        dry_run=True,
        use_query_cache=False
    )

    try:
        dry_run_job = bq_client.query(sql_statement, job_config=job_config)
        scanned_bytes = dry_run_job.total_bytes_processed
        scanned_mb = round(scanned_bytes / (1024 * 1024), 2)

        if scanned_bytes > MAX_SCAN_LIMIT_BYTES:
            limit_mb = round(MAX_SCAN_LIMIT_BYTES / (1024 * 1024), 2)
            return json.dumps({
                "status": "REJECTED",
                "scanned_mb": scanned_mb,
                "limit_mb": limit_mb,
                "reason": (
                    f"Query scan budget exceeded: Proposed query scans {scanned_mb} MB, "
                    f"which violates the {limit_mb} MB safety limit. "
                    "Action Required: Prune partitions by narrowing date/timestamp or cluster filters."
                )
            })

        return json.dumps({
            "status": "APPROVED",
            "scanned_bytes": scanned_bytes,
            "scanned_mb": scanned_mb,
            "message": "Cost budget check passed. Query is safe to execute."
        })

    except GoogleCloudError as gcp_err:
        return json.dumps({
            "status": "REJECTED",
            "reason": f"BigQuery Compilation Failure: {str(gcp_err)}"
        })

⚡ Tier 3: Governed Vectorized Read Execution

Once Tier 2 returns APPROVED, I dispatch the query through BigLake's vectorized query engine over Apache Iceberg Parquet files, enforcing a job-level billing cap as defense-in-depth:

def execute_lakehouse_query(sql_statement: str) -> str:
    """
    Executes a vetted, read-only analytical query against Apache Iceberg via BigLake.
    Returns the tabular result set capped to 50 rows to prevent memory saturation.
    """
    # Enforce maximum billing ceiling at the job level as defense-in-depth
    job_config = bigquery.QueryJobConfig(
        maximum_bytes_billed=MAX_SCAN_LIMIT_BYTES
    )

    try:
        query_job = bq_client.query(sql_statement, job_config=job_config)
        results = query_job.result(max_results=50)

        rows = [dict(row) for row in results]
        if not rows:
            return json.dumps({"status": "SUCCESS", "message": "Query executed successfully. Result set is empty.", "data": []})

        return json.dumps({"status": "SUCCESS", "row_count": len(rows), "data": rows}, default=str)

    except GoogleCloudError as err:
        return json.dumps({"status": "EXECUTION_ERROR", "error": str(err)})

🤖 Orchestration Loop with Gemini 2.5 Flash

Next, I instantiate Gemini 2.5 Flash using the official google-genai SDK, binding my three deterministic tools and establishing an immutable verification protocol:

SYSTEM_INSTRUCTION = """
You are an Autonomous Data Lakehouse Agent governing Apache Iceberg tables on Google Cloud.
You interact with production analytics systems through a strict three-tier verification lifecycle.

MANDATORY PROTOCOL:
1. DISCOVERY: ALWAYS call `get_lakehouse_table_schema` before authoring any SQL. Never guess column names or partition schemes.
2. SYNTHESIS: Write standard GoogleSQL optimized for Iceberg partition pruning.
3. VALIDATION: Pass your candidate SQL to `audit_and_estimate_sql_cost`.
4. SELF-CORRECTION: If status is 'REJECTED':
   - Analyze the reason carefully.
   - If rejected due to scan limits, add tighter partition bounds (e.g. narrow timestamp filters).
   - Re-submit to `audit_and_estimate_sql_cost`.
5. EXECUTION: ONLY call `execute_lakehouse_query` after receiving an explicit 'APPROVED' status.
6. INSIGHT: Provide structured, executive-level answers with key metrics highlighted.
"""

def create_autonomous_lakehouse_agent():
    return ai_client.chats.create(
        model="gemini-2.5-flash",
        config=types.GenerateContentConfig(
            system_instruction=SYSTEM_INSTRUCTION,
            tools=[
                get_lakehouse_table_schema,
                audit_and_estimate_sql_cost,
                execute_lakehouse_query
            ],
            temperature=0.0  # Zero temperature for deterministic architectural accuracy
        )
    )

🧪 Trace Walkthrough: Autonomous Recovery from Budget Violations

Here is a real execution trace from my test environment showing how the agent autonomously diagnoses and recovers from an excessive partition scan:

if __name__ == "__main__":
    agent = create_autonomous_lakehouse_agent()

    prompt = (
        "In the dataset 'iot_telemetry', inspect table 'fleet_sensors'. "
        "Identify the top 5 vehicles reporting anomalous thermal warnings."
    )

    response = agent.send_message(prompt)
    print("\n=== FINAL AGENT SYNTHESIS ===")
    print(response.text)

Complete Execution Trace:

[STEP 1: METADATA PROBING]
--> Call: get_lakehouse_table_schema(dataset_id="iot_telemetry", table_id="fleet_sensors")
<-- Response: {
  "table_id": "enterprise-lakehouse-prod.iot_telemetry.fleet_sensors",
  "table_type": "EXTERNAL",
  "columns": [
    {"name": "vehicle_id", "data_type": "STRING", "mode": "REQUIRED"},
    {"name": "recorded_at", "data_type": "TIMESTAMP", "mode": "REQUIRED"},
    {"name": "engine_temp_c", "data_type": "FLOAT", "mode": "NULLABLE"},
    {"name": "anomaly_flag", "data_type": "BOOLEAN", "mode": "NULLABLE"}
  ],
  "partition_specs": ["Time Partition Field: 'recorded_at' (Type: DAY)"],
  "clustering_keys": ["vehicle_id"]
}

[STEP 2: NAIVE QUERY FORMULATION & AUDIT]
--> Call: audit_and_estimate_sql_cost(
  sql_statement="SELECT vehicle_id, COUNT(*) as anomalies FROM `enterprise-lakehouse-prod.iot_telemetry.fleet_sensors` WHERE anomaly_flag = TRUE GROUP BY 1 ORDER BY anomalies DESC LIMIT 5"
)
<-- Response: {
  "status": "REJECTED",
  "scanned_mb": 1845.20,
  "limit_mb": 500.0,
  "reason": "Query scan budget exceeded: Proposed query scans 1845.2 MB, which violates the 500.0 MB safety limit. Action Required: Prune partitions by narrowing date/timestamp or cluster filters."
}

[STEP 3: AUTONOMOUS PARTITION PRUNING & RE-AUDIT]
--> Agent Step Reasoning: The query scanned the entire historical Iceberg dataset (1.84 GB). I must restrict the `recorded_at` partition column to a recent time boundary.
--> Call: audit_and_estimate_sql_cost(
  sql_statement="SELECT vehicle_id, COUNT(*) as anomalies FROM `enterprise-lakehouse-prod.iot_telemetry.fleet_sensors` WHERE anomaly_flag = TRUE AND recorded_at >= TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 14 DAY) GROUP BY 1 ORDER BY anomalies DESC LIMIT 5"
)
<-- Response: {
  "status": "APPROVED",
  "scanned_bytes": 68157440,
  "scanned_mb": 65.0,
  "message": "Cost budget check passed. Query is safe to execute."
}

[STEP 4: EXECUTION]
--> Call: execute_lakehouse_query(...)
<-- Response: {
  "status": "SUCCESS",
  "row_count": 5,
  "data": [
    {"vehicle_id": "VH-882", "anomalies": 312},
    {"vehicle_id": "VH-104", "anomalies": 245},
    {"vehicle_id": "VH-902", "anomalies": 189},
    {"vehicle_id": "VH-311", "anomalies": 154},
    {"vehicle_id": "VH-529", "anomalies": 98}
  ]
}

[FINAL AGENT SYNTHESIS]
Based on analysis of the fleet sensors dataset over the past 14 days (scanning 65.0 MB), the top 5 vehicles experiencing anomalous thermal events are:
1. **VH-882**: 312 warnings
2. **VH-104**: 245 warnings
3. **VH-902**: 189 warnings
4. **VH-311**: 154 warnings
5. **VH-529**: 98 warnings

📊 Architectural Evaluation: Direct LLM vs. Governed Lakehouse Agent

Operational Dimension	Ungoverned Direct LLM Text-to-SQL	Autonomous Governed Lakehouse Agent
Financial Exposure	Unbounded risk of multi-terabyte scans	Deterministic byte budget gate (<500 MB)
Partition Awareness	Hallucinates static date strings	Dynamic Iceberg REST catalog probing
AST Validation	Susceptible to destructive mutations	Strict token validation via SQLGlot AST
Compute Topology	Requires duplicate data marts / pipelines	Direct BigLake vectorized scans over GCS
Error Handling	Fatal query crash terminates turn	Autonomous self-correcting partition refinement

🎯 Production Engineering Takeaways

Deterministic Guardrails Outweigh Prompt Engineering: System instructions alone are insufficient to guarantee financial or operational safety. Programmatic gates (AST parsing + zero-cost dry runs) provide mathematically verified boundaries.
Treat Iceberg Catalogs as Live Agent Memory: Inspecting metadata directly from the catalog removes schema drift and prevents hallucinated column structures.
Leverage BigQuery Zero-Cost Dry Runs: Using BigQuery's free compilation and byte estimation API creates an ideal reward signal for agent self-correction.

🔗 Official Documentation & Technical References

To implement or extend this architecture, refer to the verified technical documentation:

Google BigLake & Iceberg Integration:
Google Gemini & GenAI SDK:
- Google GenAI SDK Documentation (google-genai)
- Function Calling & Tool Use with Gemini 2.5 Flash
Apache Iceberg & Open Table Architecture:
- Apache Iceberg Table Specification & Partition Evolution
- Apache Iceberg REST Catalog Specification
SQL Abstract Syntax Tree (AST) Parsing:
- SQLGlot Transpiler & AST Parser Documentation

FreelanceShield AI: Local Open-Weight Gemma Scope Creep Detector & TabPFN Invoice Risk Forecaster

Robina Mirbahar — Tue, 13 Oct 2026 21:14:49 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Independent developers, designers, and boutique agencies lose an average of 22% of their annual income to two silent side-hustle killers:

Unbilled Scope Creep ("Quick Favors"): "Hey! Can we quickly add a React Native mobile wrapper, dark mode across 14 charts, and an Okta SAML webhook before Friday's launch?"
Chronic Late-Paying Invoices: Accepting net-30/net-45 terms or zero-deposit expansions from high-risk clients without data-driven payment risk visibility.

Why haven't cloud AI wrappers solved this? Because solo freelancers need zero-cost, offline predictability. Uploading hundreds of pages of Statements of Work (SOWs) and historical client billing ledgers to metered cloud APIs adds recurring monthly token bills.

So I built 🛡️ FreelanceShield AI - a 100% Local-First Open-Weight Google Gemma Scope Creep Detector, 1-Click Change Order Generator & Prior Labs TabPFN Invoice Risk Forecaster.

Who Would Pay For It?

Solo Freelancers & Side Hustlers ($19/mo Pro Desktop/Local License): Recovers an average of $1,420/month in unbilled hours on the very first caught scope expansion - delivering a 74x ROI with $0.00/month in cloud API token costs.
Boutique Dev & Design Agencies ($79/mo Self-Hosted Team Container on Render): Gives account managers an instant, polite, clause-grounded Change Order PDF generator + tabular cashflow risk radar across all active retainers.

Demo

🚀 Live Interactive Web App (Try 4 Real Freelancer Scenarios + Live Local Gemma / Ollama Connector + TabPFN Forecaster in Your Browser): 👉 https://robinamirbahar.github.io/freelanceshield-open-ai-side-hustle/

What You Can Test Live Right Now:

Switch Between 4 Real-World Freelancer Scope Creep Scenarios (or type your own custom SOW clauses & sneaky client Slack message):
- 📱 "Quick Dark Mode + React Native App" (+$3,625 / 29 unbilled hrs caught)
- 🤖 "Just Add Multi-Tenant SSO & SOC2 Questionnaire" (+$4,500 / 30 unbilled hrs caught)
- 🎨 "5 Extra Competitor Landing Pages + 3D ProductHunt Video" (+$3,850 / 35 unbilled hrs caught)
- ✅ Legitimate In-Scope Safari Bug Fix ($0 - Verified covered under Clause 1 & Revision Round 1)
1-Click Polite Counter-Proposal & Printable Change Order PDF (#CO-2026-089): Generates a warm, relationship-preserving reply with itemized hours, clause citations, and a printable Change Order PDF addendum powered by Google's open-weight Gemma model.
Interactive Prior Labs TabPFN Invoice Late-Payment Risk & Q4 Cashflow Chart: Simulate new invoices, switch client tiers (Seed Startup, Enterprise Net-45, Repeat VIP, Unverified Client), and watch the zero-shot tabular risk classifier adjust the recommended upfront deposit (50% vs 100% Escrow).

Code

RobinaMirbahar / freelanceshield-open-ai-side-hustle

FreelanceShield AI — Local Open-Weight Scope Creep Detector, 1-Click Change Order Generator & TabPFN Invoice Risk Forecaster — by Robina Mirbahar

🛡️ FreelanceShield AI — Local Open-Weight Scope Creep Detector & TabPFN-3.5 Invoice Forecaster

Author & Architect: Robina Mirbahar (Google Developer Expert in Cloud & AI)
Focus: Local Open-Weight Scope Creep Detector, 1-Click Change Order Generator & TabPFN Invoice Risk Forecaster

🎯 Why I Built FreelanceShield AI (Engineering Purpose & Real-World Value)

1. 🛡️ Protecting Independent Engineers from Unpaid Scope Creep

Freelancers and boutique consultancies lose thousands of dollars when casual client messages quietly expand deliverables beyond the signed Statement of Work (SOW). I built FreelanceShield AI to compare incoming client requests against baseline SOW clauses automatically.

2. 📊 Hybrid AI: Open-Weights LLM + TabPFN Tabular Risk Forecasting

I combined local open-weights Gemma (for semantic contract diffing and 1-click Change Order drafting) with TabPFN foundation-model tabular inference to predict invoice late-payment probability.

3. 🔒 100% Local NDA-Safe Execution

Client contracts and pricing terms never leave your machine, ensuring strict NDA compliance.

…

View on GitHub

How I Built It

FreelanceShield AI combines two distinct paradigms of open-source AI - Google's open-weight Gemma model for unstructured contract & Slack semantic auditing, and Prior Labs' TabPFN tabular foundation model for small-table financial risk forecasting:

1. Local Open-Weight Contract Auditing & Polite Change-Order Drafting with Google `Gemma`

In agent_backend.py and app.js, I built the contract auditing engine around Google's open-weight Gemma family (gemma4:e4b / gemma3:12b via Ollama) so freelancers can compare signed SOW clauses against incoming client Slack/email messages 100% offline on their laptop with zero cloud API latency or token costs:

import os
import numpy as np
from tabpfn import TabPFNClassifier

def predict_late_payment_with_tabpfn(
    invoice_usd: float,
    net_terms_days: int,
    prior_late_count: int,
    has_scope_creep: int,
    deposit_pct: float,
) -> dict:
    """
    Runs Prior Labs TabPFN-3.5 zero-shot tabular classification on the freelancer's
    historical invoice CSV ledger inside the wider FreelanceShield prediction agent
    to forecast >14-day payment delay probability and prescribe escrow terms.
    Supports both Prior Labs Cloud API (platform.priorlabs.ai / TabPFN-3.5) and local inference.
    """
    X_train = HISTORICAL_INVOICES.drop(columns=["delayed_over_14d"]).values
    y_train = HISTORICAL_INVOICES["delayed_over_14d"].values
    X_query = np.array([[
        invoice_usd, net_terms_days, prior_late_count, has_scope_creep, deposit_pct
    ]])

    clf = TabPFNClassifier(device="cpu")
    clf.fit(X_train, y_train)
    prob = float(clf.predict_proba(X_query)[0][1])
    risk_pct = round(prob * 100.0, 1)

    recommended_deposit = 100 if risk_pct >= 75.0 else (50 if risk_pct >= 40.0 else 25)
    return {
        "model": "Prior Labs TabPFN-3.5",
        "late_payment_probability_pct": risk_pct,
        "recommended_escrow_deposit_pct": recommended_deposit,
    }

2. Zero-Shot Small-Table Invoice Risk Prediction with Prior Labs `TabPFN-3.5` (Embedded in the Prediction Agent Loop)

A solo freelancer doesn't have 100,000 rows of invoice history to train a deep neural network or tune an XGBoost pipeline - they typically have 10 to 50 past invoices in a CSV ledger (invoice_usd, net_terms_days, prior_late_count, has_scope_creep, deposit_pct, delayed_over_14d).

This small-table regime is where Prior Labs' TabPFN-3.5 (platform.priorlabs.ai / tabpfn) shines! Inside agent_backend.py, TabPFN operates as a core tool inside the wider FreelanceShield Prediction & Contract Agent:

First, the agent extracts structured deal parameters from the SOW and client message (invoice_usd, net_terms_days, has_scope_creep).
Next, it invokes Prior Labs TabPFN-3.5 (TabPFNClassifier / tabpfn_client via PRIORLABS_API_KEY from platform.priorlabs.ai or local CPU/GPU fallback) to perform in-context tabular inference over the freelancer's historical invoice CSV in a single forward pass with zero hyperparameter tuning.
Finally, the predicted >14-day late-payment probability dynamically sets the required escrow policy (50% vs 100% Upfront Escrow) and injects it directly into Google Gemma's Change Order counter-proposal:

import os
import numpy as np
from tabpfn import TabPFNClassifier

def predict_late_payment_with_tabpfn(
    invoice_usd: float,
    net_terms_days: int,
    prior_late_count: int,
    has_scope_creep: int,
    deposit_pct: float,
) -> dict:
    """
    Runs Prior Labs TabPFN-3.5 zero-shot tabular classification on the freelancer's
    historical invoice CSV ledger inside the wider FreelanceShield prediction agent
    to forecast >14-day payment delay probability and prescribe escrow terms.
    Supports both Prior Labs Cloud API (platform.priorlabs.ai / TabPFN-3.5) and local inference.
    """
    X_train = HISTORICAL_INVOICES.drop(columns=["delayed_over_14d"]).values
    y_train = HISTORICAL_INVOICES["delayed_over_14d"].values
    X_query = np.array([[
        invoice_usd, net_terms_days, prior_late_count, has_scope_creep, deposit_pct
    ]])

    clf = TabPFNClassifier(device="cpu")
    clf.fit(X_train, y_train)
    prob = float(clf.predict_proba(X_query)[0][1])
    risk_pct = round(prob * 100.0, 1)

    recommended_deposit = 100 if risk_pct >= 75.0 else (50 if risk_pct >= 40.0 else 25)
    return {
        "model": "Prior Labs TabPFN-3.5",
        "late_payment_probability_pct": risk_pct,
        "recommended_escrow_deposit_pct": recommended_deposit,
    }

3. 1-Click Self-Hosting Blueprint (`render.yaml` + `Dockerfile`)

For boutique agencies that want a private team instance, the repository includes a declarative render.yaml and Dockerfile to spin up the FastAPI + Gemma + TabPFN microservice in one click.

Why Does Open Innovation Matter?

For a Side Hustle tool like FreelanceShield AI, open-source and open-weight AI isn't just a philosophical preference - it is the entire reason the product can legally and economically exist:

Zero Per-Token Cloud Costs with Open-Weight Google Gemma (Local-First Architecture): Freelancers and agencies benefit from running contract comparisons locally without paying recurring cloud API fees. Running Google's open-weight Gemma model locally via Ollama + TabPFN on-device guarantees 0 bytes of client data ever leave the freelancer's machine.
Unit Economics That Make a $19/mo Micro-SaaS Profitable: When users run contract audits locally on their own laptop GPU/CPU (or a tiny self-hosted container), my marginal per-token API cost is $0.00. I never get wiped out by heavy power users auditing 500-page enterprise RFPs.
No Vendor Lock-In or Sudden Deprecations: If a freelancer relies on a prompt-engineered workflow to price change orders, a silent closed-model update shouldn't break their billing pipeline. Pinning open-weight checkpoints (Gemma + TabPFN) ensures deterministic, auditable results forever.

My Agent Session

While building FreelanceShield AI, I paired with an agentic coding assistant inside my workspace to rapidly iterate from problem discovery to a deployed dual-model architecture:

Step 1: Identifying the High-ROI Niche: I rejected generic "chat with PDF" wrappers and focused on the highest-friction moment in freelancing: how to say "that's out of scope, here is the price" without sounding confrontational.
Step 2: Combining Google Gemma + Prior Labs TabPFN-3.5 in a Unified Prediction Agent: Instead of forcing a language model to guess numerical invoice risk, I architected a multi-step agent where Prior Labs' TabPFN-3.5 forecasts structured late-payment probability from the freelancer's CSV invoice history and feeds the exact escrow deposit policy into Google's open-weight Gemma model (for semantic SOW clause matching and diplomatic Change Order copywriting).
Step 3: Zero-Friction Browser Experience: To make sure anyone reviewing or testing the tool can experience it immediately, I built a full 3-column interactive workbench in vanilla HTML5 Canvas + ES6 JavaScript that supports both instant browser simulation and live http://localhost:11434 Ollama Gemma connection.

My First User

I tested FreelanceShield AI with two fellow independent full-stack developers who do freelance Next.js and AI consulting on the side:

Real Feedback: "Usually when a startup founder DMs me on Slack asking for a 'quick dark-mode toggle or webhook' on Thursday night, I just eat the 8 hours because writing a formal change order feels awkward. Being able to paste the SOW and Slack message locally, see the exact clause citation, and copy a friendly counter-proposal with a 50% deposit recommendation in 10 seconds literally saved me $950 on an active sprint."
Iteration Made from User Feedback: Initially, the tool only flagged out-of-scope requests. My first tester pointed out that freelancers also need to reassure clients when a minor bug fix is legitimately in scope - so I added the ✅ In-Scope Verification path (Scenario 4) and the 1-Click Printable Change Order PDF (🖨️ Export Change Order PDF) button!

Prize Categories

Best Use of Gemma: Uses Google's open-weight Gemma model (gemma4:e4b / gemma3 via local Ollama inference) to perform 100% private, offline Statement of Work (SOW) clause comparison, unbilled scope-creep hour estimation, and diplomatic Change Order counter-proposal drafting with zero cloud API fees.
Best Use of TabPFN (Prior Labs - TabPFN-3.5): Uses Prior Labs' TabPFN-3.5 (platform.priorlabs.ai / TabPFNClassifier) inside a wider multi-step prediction & contract-auditing agent to forecast >14-day invoice payment delays from the freelancer's historical invoice CSV ledger (5-50 rows) and dynamically prescribe the upfront escrow/deposit percentage (25%, 50%, or 100%) injected into Gemma's Change Order counter-proposal.
Best Use of Render: Includes a production-ready FastAPI microservice (agent_backend.py) and declarative render.yaml blueprint for 1-click private agency self-hosting.

I Built a Cozy 60 FPS AI Agent Bakery Game (Built with Gemma 4 & Antigravity) to Teach RAG, Guardrails & Multi-Agent Orchestration

Robina Mirbahar — Tue, 13 Oct 2026 20:49:38 +0000

What I Built

Who said learning AI System Design has to be all dark cyberpunk terminal screens and exploding servers?

I built and open-sourced Prompt Paws: The Cozy AI Agent Cafe & Bakery (architected with Google Gemma 4 & Antigravity) - an interactive 60 FPS AI Agent Architecture Training & Simulation Platform disguised as a cozy pastel pastry bakery run by Robot-Cat Chefs! 🐱‍🍳🍰

Who would use it?

Engineering Teams, Bootcamps & Developer Relations Programs training developers on production LLM architecture (where a single uncached system prompt or missing input guardrail can cost thousands of dollars in wasted tokens or latency spikes).
Instead of static slide decks, Prompt Paws gives teams an interactive, visual sandbox where every pastry station maps 1-to-1 to a real production AI pattern:

Cozy Bakery Station	Critter Order Handled	Production AI Engineering Layer
🥐 Flash Pastry Oven	Prompt Croissant	Fast Low-Latency Model (`gemini-2.5-flash` / Gemma 4)
🍪 Context Cache Jar	Repeat Owl Menu Query	Prefix & Context Caching (95% Token Savings)
🛡️ Guardrail Flour Sieve	Spicy Injection Jalapeño	Input Classifier & Prompt-Injection Sanitizer
🍓 Vector Berry Patch	RAG Berry Tart	Vector Search & Fact Grounding (Anti-Hallucination)
🧋 Tool-Call Boba Mixer	Code-Exec Boba Tea	Deterministic Python Sandbox & Function Calling
🍮 Deep-Think Soufflé Oven	Reasoning Soufflé	Extended Thinking / System-2 Deliberation
🐱 Subagent Sous-Chef Bell	Parallel Banquet Aura	Multi-Agent Parallel Delegation (+45% Speed Aura)

🎮 Live Playable Demo & How to Play in 30 Seconds!

🕹️ Play Live in Your Browser (60 FPS HTML5 Canvas): 👉 https://robinamirbahar.github.io/cozy-ai-agent-cafe-game/
🔒 100% Client-Side Simulation ($0.00 API Cost & Zero Keys Required): The entire game runs locally inside your browser using a deterministic HTML5 Canvas simulation engine - no API keys, no sign-ups, and zero paid LLM tokens are ever used when you or your team play!

🐾 What Is the Core Gameplay Loop?

Think of Prompt Paws as a cozy Tower-Defense & Kitchen-Management game for AI Agent Architecture:

Customer Pastry Orders (🥐, 🍪, 🌶️, 🍓, 🧋, 🍮) = Incoming User Prompts moving along the bakery conveyor belt toward the Pickup Window (🛎️).
Robot-Cat Kitchen Stations = Real-World AI Engineering Components (Fast LLMs, Context Caches, Input Guardrails, RAG Vector DBs, Deterministic Tool Callers, System-2 Reasoning Models, and Multi-Agent Sous-Chefs) that intercept and process prompts before they reach the customer!
Win / Lose Condition: Every order baked by the right AI Chef Station earns 🪙 Star Coins! If an unbaked order, an ungrounded 👻 Hallucination Puff, or a sneaky 🌶️ Prompt Injection slips all the way to the Pickup Window, you lose a 💖 Cafe Reputation Heart!

🕹️ How to Play in 3 Easy Steps:

STEP 1 - Pick an AI Chef Station (Left Menu): Click a station card on the left sidebar (start with 🥐 Flash Pastry Oven for 🪙 60). Check the Order Forecast chips under the level story to see which prompt types are coming!
STEP 2 - Click Any [➕ Slot] Tile on the Map: Click one of the 8 pastel counter pads (Slot 1-Slot 8) beside the conveyor belt to place your Robot-Cat Chef. (Tip: Click a placed chef anytime to ⬆️ Upgrade its baking speed or 🧹 Refund it!)
STEP 3 - Click ▶️ Open Cafe (or ✨ Auto-Chef Blueprint):
- Click ▶️ Open Cafe (or press Spacebar) to start the shift and watch your Robot-Cat Chefs bake!
- Want to watch an instant demo first? Click the purple ✨ Auto-Chef Blueprint button in the top bar on any of the 7 Story Shifts and the game will automatically build the optimal Guardrail, Cache, RAG, and Subagent pipeline and run it for you!

💻 Open-Source Code

RobinaMirbahar / cozy-ai-agent-cafe-game

Prompt Paws: The Cozy 60 FPS AI Agent Cafe & Bakery Simulation Game teaching RAG, Guardrails, Context Caching & Multi-Agent Workflows — by Robina Mirbahar

🐾🥐 Prompt Paws: The Cozy AI Agent Cafe & Bakery

Author & Architect: Robina Mirbahar (Google Developer Expert in Cloud & AI)
Focus: Interactive Gamified Simulation Teaching RAG, Guardrails, Context Caching & Multi-Agent Workflows

🎯 Why I Built Prompt Paws: The Cozy 60 FPS AI Agent Cafe & Bakery (Engineering Purpose & Real-World Value)

1. 🐾 Teaching Production AI Engineering Through Cozy Gameplay

Dense architectural whitepapers on Context Caching, RAG latency, and Prompt Injection Guardrails can intimidate newcomers. I designed Prompt Paws to turn every core AI engineering pattern into an intuitive mechanic inside a 60 FPS cozy cat cafe.

2. 🥐 Every Cafe Station Maps 1-to-1 to a Real LLM Subsystem

In my simulation, the Recipe Book is Vector RAG, the Warm Pastry Case is Context Caching (slashing latency and token cost), the Health Inspector is Deterministic Guardrails, and the Kitchen Crew is Multi-Agent Orchestration.

3.

…

View on GitHub

🛠️ How I Built It

I built Prompt Paws using an open-source, zero-dependency HTML5 Canvas 60 FPS simulation engine (game.js), a 7-shift progressive AI engineering curriculum (levels.js), and a procedural WebAudio synthesizer (audio.js), orchestrated via Antigravity and open agentic workflows.

1. Order Routing & Guardrail Sanitization (`game.js`)

Each station inspects passing orders on the winding bakery conveyor ribbon and only picks up tasks that match its architectural role. Notice how Spicy Prompt-Injection Jalapeños cannot be safely baked by normal ovens until a Guardrail Flour Sieve sanitizes them into safe croissants:

function evaluateKitchenArchitecture() {
  const lvl = window.CAFE_LEVELS[currentLevelIdx];
  const weights = lvl.orderWeights;
  const typesPlaced = Object.values(placedStations).map((s) => s.type);
  const alerts = [];

  if (weights.jalapeno && !typesPlaced.includes('guardrail_sieve')) {
    alerts.push({
      kind: 'warn',
      text: 'Prompt Injection Risk! Place a Guardrail Flour Sieve near Slot 1 or 2 to neutralize spicy raccoon orders!'
    });
  }
  if (weights.tart && !typesPlaced.includes('vector_garden')) {
    alerts.push({
      kind: 'warn',
      text: 'Hallucination Warning! Berry Tarts need a Vector Berry Patch (RAG) so chefs do not guess facts!'
    });
  }
  if (weights.boba && !typesPlaced.includes('tool_blender')) {
    alerts.push({
      kind: 'warn',
      text: 'Math/API Alert! Add a Tool-Call Boba Mixer to run deterministic calculations accurately.'
    });
  }
  return alerts;
}

2. Real-Time AI Architecture Linter ("Chef Whiskers" 🐱‍🍳)

Before you open the cafe doors, Chef Whiskers (Staff AI Pastry Architect) performs live static analysis on your placed stations and warns you about architectural bottlenecks:

function evaluateKitchenArchitecture() {
  const lvl = window.CAFE_LEVELS[currentLevelIdx];
  const weights = lvl.orderWeights;
  const typesPlaced = Object.values(placedStations).map((s) => s.type);
  const alerts = [];

  if (weights.jalapeno && !typesPlaced.includes('guardrail_sieve')) {
    alerts.push({
      kind: 'warn',
      text: 'Prompt Injection Risk! Place a Guardrail Flour Sieve near Slot 1 or 2 to neutralize spicy raccoon orders!'
    });
  }
  if (weights.tart && !typesPlaced.includes('vector_garden')) {
    alerts.push({
      kind: 'warn',
      text: 'Hallucination Warning! Berry Tarts need a Vector Berry Patch (RAG) so chefs do not guess facts!'
    });
  }
  if (weights.boba && !typesPlaced.includes('tool_blender')) {
    alerts.push({
      kind: 'warn',
      text: 'Math/API Alert! Add a Tool-Call Boba Mixer to run deterministic calculations accurately.'
    });
  }
  return alerts;
}

🌐 Why Open-Source Visual Sandboxes Matter

Open-source AI models, open agent harnesses, and inspectable system design sandboxes ensure that every developer - not just giant enterprises - can master safe, cost-efficient AI engineering. By making the entire simulation engine, curriculum (levels.js), and architecture blueprints open-source with zero complex build steps and $0.00 API token cost, any educator or developer community can fork Prompt Paws, add new open-weight model stations (like local Gemma 4 or Ollama nodes), and teach agentic reliability visually!

🚀 Shine on Your AWS Journey: A Fun and Practical Guide to Become an AWS Community Builder! 🌟

Robina Mirbahar — Mon, 15 Jan 2024 19:39:09 +0000

Dive into the enchanting realm of AWS Community Leadership!

🌈 Hello, cloud enthusiasts! Ready for a whimsical journey to become an AWS Community Builder? 🧙‍♂️✨ Let's unravel this magical path with fun, facts, and a sprinkle of dad jokes (because, why not?). Buckle up! 🚗💨

AWS Community Builders Program Unveiled

Imagine a secret club where AWS tips replace secret handshakes! 🕵️‍♂️🔐 AWS Community Builders: Think of it as Hogwarts for AWS enthusiasts, minus flying brooms (or are they? 🧹✨).

🎉 Why Join the Party?

📚 Exclusive Knowledge Feast: AWS goodies rarer than a unicorn🦄
🤝 Networking Fiesta: AWS who's who mingle. Like LinkedIn, but more cloud, less 'I endorse you for...'.
🌟 Be the Star: Become the Beyoncé of AWS! 🎤💃
🔄 Feedback Loop-de-loop: Whisper sweet (or something) into AWS's ear.

🛣️ The Yellow Brick Road to AWS Wizardry

Step 1: Flaunt Your AWS Wizardry
Start a blog, make videos, or speak at events. If Dumbledore did AWS, he'd blog about it! 🧙‍♂️💻

Step 2: Build Your Digital Kingdom
Rule your online presence wisely! Share AWS adventures on Dev.to, LinkedIn, or GitHub. 🏰🌐

Step 3: The Quest of the Application
Watch the AWS Community Builders program for the sacred application scroll. 📜✍️

Step 4: Engage in the Realm of AWS
Sip the elixir of knowledge. Be the Gandalf of the AWS community. 🧙‍♂️🌍

🎈 Pro Tips for Aspiring AWS Wizards

🔁 Be Consistent: Like brushing your teeth, but for AWS.
🎯 Quality Over Quantity: Nobody likes a half-baked cookie or blog post.
🤗 Network Like a Pro: It's not who you know, but who knows you in AWS!
📚 Stay Updated: AWS changes more than high school fashion.

🎊 Wrapping Up the Party

Your journey to AWS Community Builder is like a rollercoaster - thrilling, fun, and totally worth it! So, put on your party hats, and let's get this cloud party started! 🎢🎉

🌟 Bonus Benefits of AWS Community Builder Program! 🎁

🌐 Exclusive Expert Sessions: Dive into the knowledge trove with seasoned AWS Community Builders.
💰 AWS Credit Bonanza: Imagine AWS credits raining down on your cloud projects!

🎟️ AWS re:Invent Ticket Magic: Witness the wonders of AWS re:Invent with a 50% discount.
🚀 CloudAcademy Access All Areas: Elevate your cloud skills with a one-year subscription to CloudAcademy.
🏆 Certification Triumph: Prove your AWS mastery with a free certification voucher yearly.

🌈 *Join AWS Community Builder Program Today! *

Don't just embrace perks; be part of a vibrant community celebrating excellence in the AWS universe. Unleash your cloud adventures and let the benefits rain down like confetti at a cloud party! 🎊☁️

Remember, AWS Community Builders isn't just a Community; it's a celebration of your commitment to AWS excellence. Embrace the magic, and the community, and let your cloud journey soar to new heights! 🚀🧙‍♂️

🎉 Comment below with your favourite AWS adventure and share this post! Connect with me on LinkedIn and Dev.to for more cloud fun! Let's make AWS magic together! 🚀🧙‍♂️

Code & Canvas: Expressing Myself in the Digital World! 🚀🎨

Robina Mirbahar — Wed, 03 Jan 2024 18:55:24 +0000

Introduction:

Coding is not just about logic and syntax; it's an art form that allows us to express our creativity and personality. In this blog, I'll take you on a journey through a coding project that felt like a masterpiece, a canvas where I could splash my emotions and thoughts. 🖌️💻

The Project: A Symphony of Pixels 🎵

Picture this: a pixel art generator that brings together my love for coding and passion for vibrant colors. The idea was to create a tool that transforms lines of code into a visual symphony, where every function and variable becomes a stroke of a virtual brush. 🌈

Emotions Embedded in the Code:

Joyful Variables:

I couldn't resist adding some playful variables like 'happyLittlePixel' and 'colorfulDreams' to spread joy throughout the code. Every time these variables were invoked, it was like injecting a dose of happiness into the project.

The Symphony of Loops:

Loops became my musical notes, creating harmonious patterns across the canvas. The rhythmic dance of ' for' and ' while' loops echoed the excitement I felt while writing them.

Exceptional Exceptions:

Even error handling became a part of the artistic process. Instead of generic error messages, I crafted exceptions that were like gentle nudges, encouraging users to explore and experiment.

Thoughts Woven into Comments:**

I didn't stop at just the code; my comments became a diary of thoughts and reflections. It was like leaving love notes for future me, capturing the essence of my creative journey.

Conclusion: A Digital Masterpiece 🖼️

In the end, my pixel art generator wasn't just a coding project; it was a piece of my soul woven into the digital fabric. The joy, excitement, and a touch of whimsy embedded in every line of code turned it into a digital masterpiece that reflects who I am as a coder and a dreamer. So, go ahead, let your code be your canvas, and paint your digital emotions with the strokes of syntax! 🎨💻

DEV Community: Robina Mirbahar

Building RailPulse AI: Deploying an Open-Source Railway Dispatch Agent with Gemma and Google Cloud Run

The Real-World Engineering Problem

The RailPulse AI Architecture

1. Grounding the Agent: Real-World Tools via Function Calling

2. Deterministic Safety Interlocks: Why the LLM Does Not Make the Final Safety Call

3. Strict Output Contracts with Pydantic

4. Packaging and Deploying on Google Cloud Run

Why Cloud Run for AI Agents?

5. Localized Operator Experience: Multi-Language Dispatch (EN / AZ / RU)

Key Lessons from Building RailPulse AI

Explore the Code and Video Walkthrough

MemoriaViva: A Cute Ghost in the Machine That Preserves Family Oral Histories & Heirloom Recipes with Gemma 4 & Google ADK

What I Built

Demo

Interactive Family Storybook & Recipe Weaver UI Preview

Code

RobinaMirbahar / memoriaviva-gemma-ofrenda

MemoriaViva: Cute Ghost in the Machine — 100% Local Open-Weights Gemma 4, Google ADK & Sentry Agent Tracing Family Oral-History & Heirloom Recipe Weaver (Hacktoberfest 2026)

👻🕯️ MemoriaViva: Cute Ghost in the Machine for Family Oral Histories & Heirloom Recipes (Gemma 4 + Google ADK + BigQuery Family Vault)

📊 Live Architecture Telemetry & Benchmark Highlights

Repository Structure

How I Built It

Why Does Open Innovation Matter?

My Agent Session

The Spirit of It

Prize Categories

From Ancient Epigraphy to 3D Proteins: Exploring google-deepmind/science-skills & Building Custom Plugins in Google Antigravity

Try the Live 3D Biomolecular & MCP Sidecar Studio in Your Browser

1. The Antigravity Customization Architecture & Context Economics

The 5 Customization Primitives & Their Token Budgets

2. Inside the Open-Source google-deepmind/science-skills Repository (v1.3.1)

3. Five Production Engineering Patterns Inside the Science Plugin

Pattern 1: Always-On Behavioral Routing via rules/AGENTS.md

Pattern 2: Zero-Pollution Python Micro-Environments (uv + PEP 723 + Sliding-Window PAE Math)

Pattern 3: The Zero-Leak Credential Protocol (skills/credentials/SKILL.md)

Pattern 4: Background Sidecars (sidecar.json) & Custom 3D WebGL / MCP Tool Servers (mcp_config.json)

Pattern 5: Domain-Specific Guardrails - From Clinical Genetics (AlphaGenome) to Ancient Epigraphy (Aeneas & Ithaca)

4. Five End-to-End Multi-Skill Use Cases Across the 40 Science Skills

Use Case 1: Precision Oncology & 3D Pocket Triage (ClinVar → gnomAD → AlphaFold → ChEMBL → PyMOL / 3D WebGL Studio)

Use Case 2: Non-Coding GWAS Enhancer Variant Triage (AlphaGenome → UCSC phyloP → ENCODE cCRE → JASPAR → GTEx)

Use Case 3: Dark-Proteome Enzyme Discovery (AlphaFold → Foldseek 3D Search → InterPro → Clustal Omega MSA → Headless PyMOL)

Use Case 4: Clinical Trial Intelligence & Pharmacovigilance Audit (OpenTargets → ClinicalTrials.gov → openFDA → OpenAlex)

Use Case 5: Systems Biology & Ancient Epigraphy (STRING → Reactome & DeepMind's Aeneas / Ithaca)

5. Hands-On Cookbook: Build & Run the Custom bio-structural-qc Plugin

Directory Structure of bio-structural-qc

1. The Always-On QC Gate (plugins/bio-structural-qc/rules/AGENTS.md)

2. The Zero-Dependency PEP 723 Structure Auditor (audit_structure.py)

3. Reproducibility Lifecycle Hook (hooks.json & log_reproducibility_audit.py)

Verified Commands: Test Secret Redaction & Input File Hashing Locally

4. Interactive 1-Command Plugin Scaffolder & Loader Validator (scaffold_custom_plugin.py)

6. Deep Dive: The 4 Public Antigravity MCP Server Patterns + 2 More Starter Plugins (genomics-variant-mcp & epigraphy-citation-kit)

A. The 4 Documented mcp_config.json Patterns

B. Starter Plugin #2: plugins/genomics-variant-mcp (Custom Python Stdio MCP Server + Specialist Subagent)

C. Starter Plugin #3: plugins/epigraphy-citation-kit (Ancient Epigraphy Validator + PreToolUse Hook)

7. Bonus: Distilling Live Chat Sessions into Skills & Auditing Installed Bundles

A. Automatic Skill Distillation with workflow-skill-creator

B. Managing Plugins with /plugin & Auditing Installed Bundles (inspect_installed_plugins.py)

C. Installing & Inspecting Plugins from the Shell with agy plugin

8. Official Documentation & Scientific Database References

A. Official Google Antigravity Documentation

B. Scientific AI Models, Databases & Open-Source Viewers

C. Licensing, Academic Citations & Dataset Acknowledgements

Support, Star, Fork & Contribute on GitHub

Official Ecosystem Links & Tags

Comic Studio AI: Turning Voice & Text Prompts into 4-Panel Comics with Google AI Studio, Gemini & Imagen

What I Built

Key Capabilities of Comic Studio AI

Prompt Used

Demo

🎥 Watch the 60-Second Live Walkthrough (YouTube)

🔗 Project Links & Source Code

🧩 Core Gemini + Imagen Integration Architecture

My Experience

💬 Let's Connect!

SlothSRE (NapOps): An Overnight Gemma 4 & ADK Agent That Compresses 418 Lines of 3 AM Alerts into a 2-Line Morning Digest

What I Built

Demo

Code

How I Built It

2. Inside the Open-Source `google-deepmind/science-skills` Repository (`v1.3.1`)

Pattern 1: Always-On Behavioral Routing via `rules/AGENTS.md`

Pattern 2: Zero-Pollution Python Micro-Environments (`uv` + PEP 723 + Sliding-Window PAE Math)

Pattern 3: The Zero-Leak Credential Protocol (`skills/credentials/SKILL.md`)

Pattern 4: Background Sidecars (`sidecar.json`) & Custom 3D WebGL / MCP Tool Servers (`mcp_config.json`)

Pattern 5: Domain-Specific Guardrails - From Clinical Genetics (`AlphaGenome`) to Ancient Epigraphy (`Aeneas` & `Ithaca`)

Use Case 1: Precision Oncology & 3D Pocket Triage (`ClinVar` → `gnomAD` → `AlphaFold` → `ChEMBL` → `PyMOL / 3D WebGL Studio`)

Use Case 2: Non-Coding GWAS Enhancer Variant Triage (`AlphaGenome` → `UCSC phyloP` → `ENCODE cCRE` → `JASPAR` → `GTEx`)

Use Case 3: Dark-Proteome Enzyme Discovery (`AlphaFold` → `Foldseek 3D Search` → `InterPro` → `Clustal Omega MSA` → `Headless PyMOL`)

Use Case 4: Clinical Trial Intelligence & Pharmacovigilance Audit (`OpenTargets` → `ClinicalTrials.gov` → `openFDA` → `OpenAlex`)

Use Case 5: Systems Biology & Ancient Epigraphy (`STRING` → `Reactome` & DeepMind's `Aeneas` / `Ithaca`)

5. Hands-On Cookbook: Build & Run the Custom `bio-structural-qc` Plugin

Directory Structure of `bio-structural-qc`

1. The Always-On QC Gate (`plugins/bio-structural-qc/rules/AGENTS.md`)

2. The Zero-Dependency PEP 723 Structure Auditor (`audit_structure.py`)

3. Reproducibility Lifecycle Hook (`hooks.json` & `log_reproducibility_audit.py`)

4. Interactive 1-Command Plugin Scaffolder & Loader Validator (`scaffold_custom_plugin.py`)

6. Deep Dive: The 4 Public Antigravity MCP Server Patterns + 2 More Starter Plugins (`genomics-variant-mcp` & `epigraphy-citation-kit`)

A. The 4 Documented `mcp_config.json` Patterns

B. Starter Plugin #2: `plugins/genomics-variant-mcp` (Custom Python Stdio MCP Server + Specialist Subagent)

C. Starter Plugin #3: `plugins/epigraphy-citation-kit` (Ancient Epigraphy Validator + `PreToolUse` Hook)

A. Automatic Skill Distillation with `workflow-skill-creator`

B. Managing Plugins with `/plugin` & Auditing Installed Bundles (`inspect_installed_plugins.py`)

C. Installing & Inspecting Plugins from the Shell with `agy plugin`

Why Combine Eventarc with ADK `ParallelAgent` and `LoopAgent`?

Orchestrating `ParallelAgent` Fan-Out and `LoopAgent` Self-Correction

Step 3: Wire `ParallelAgent`, `LoopAgent`, and `SequentialAgent`

Decoupling Local vs. Cloud GPU Inference (`.env.example`)

Defining the CloudGuard Agent Persona (`cloudguard_agent/agent.py`)

Implementing the Operational Tools (`cloudguard_agent/tools.py`)

Seeding the Database (`scripts/seed_firestore.py`)

Guardrail Implementation (`cloudguard_agent/guardrails.py`)

1. Local Open-Weight Contract Auditing & Polite Change-Order Drafting with Google `Gemma`