DEV Community: Tanaike

Beyond Passive AI Rewrites and Vibe Coding in Google Docs

Tanaike — Tue, 27 Oct 2026 05:37:22 +0000

Scaling a Multimodal AI Writing and Code Review Coach Across Classrooms and Research Labs with Gemini and Google Apps Script

In my previous article—Building a Multimodal, Suggestion-Based AI Writing Coach with Gemini and Google Docs—I introduced DocuMentor AI, an open-source Google Docs add-on built with Google Apps Script, the Google Docs API (v1), and the Gemini API (gemini-3.8-flash / gemini-4-argon). Instead of overwriting a writer's draft directly, DocuMentor AI uses the newest Google Docs API Suggestion & Comment Management features (WriteControl.writeMode = "SUGGEST", addCommentReply, insertComment, acceptSuggestion, rejectSuggestion, and deleteComment) to turn Google Docs into an interactive, multimodal writing coach.

Shortly after publishing that first article, I received enthusiastic feedback from educators, Google Developer Experts (GDEs), academic researchers, and enterprise practitioners. While they loved how the tool preserves author agency—especially through 💡 Hint-Only Mode and the 🎓 Writing Coach & Learning Summary dialog—they raised a crucial practical question for schools, universities, and organizations:

"How can we deploy DocuMentor AI across a school, university lab, or company domain where students and end users are not allowed to access Google AI Studio to create their own Gemini API keys—without risking an API key leak in a shared Google Doc, and without asking non-coder IT administrators to rewrite JavaScript code?"

At the same time, while reflecting on how DocuMentor AI's underlying engine works, I came up with another new idea of my own: because DocuMentor AI extracts every line in a Google Doc as an independent block and applies non-destructive inline diffs (WriteMode.SUGGEST), Socratic hints (insertComment), and educational replies (addCommentReply), what if we use it not only for natural-language manuscripts, but also as an interactive Code Review & Programming Coach for software engineers and computer science students? Rather than blindly copy-pasting AI-generated scripts ("vibe coding"), learners could paste source code written in any programming language (Python, JavaScript, TypeScript, Go, Java, C++, Rust, SQL, Google Apps Script, etc.) into Google Docs and learn what is wrong in their code, why it fails, and how to fix it line by line.

In this follow-up article (Part 2), I present DocuMentor AI v1.0.3 alongside this new multi-language code coaching workflow:

1. Unified Dual-Mode Deployment (Individual Mode + School, Research Lab & Organization Mode): With a single unified codebase, DocuMentor AI now seamlessly supports both 👤 Individual Personal Setup (UserProperties) and 🏫 Zero-Code School, Organization & Academic Lab Deployment (ScriptProperties + Private Google Workspace Marketplace Add-on).
2. Multi-Language Interactive Code Review & Script Coaching (My New Use Case for Engineer Training): Without changing a single line of the add-on's code, DocuMentor AI serves as a language-agnostic, GitHub-style inline code reviewer and programming tutor inside Google Docs—capable of coaching learners across Python, JavaScript, TypeScript, C++, Go, SQL, Google Apps Script, and more.

Below, I explain the dual-deployment architecture, why this paradigm is transformative for academia, classrooms, and multi-language software engineer training, and walk through three live execution demonstrations: 💡 Hint-Only Mode, 🚀 Suggest & Coach Mode with resolved review history, and 💻 Interactive Code Review & Script Learning (demonstrated with a beginner Google Apps Script example).

GitHub Repository: https://github.com/tanaikech/DocuMentorAI
Previous Article (Part 1): Building a Multimodal, Suggestion-Based AI Writing Coach with Gemini and Google Docs
👤 Individual Installation Guide: INSTALL_INDIVIDUAL.md
🏫 School, University & Organization Deployment Guide: INSTALL_ORGANIZATION.md

1. The Deployment Challenge in Education, Research Labs & Organizations

When an individual developer or writer uses DocuMentor AI on their personal Google account, pasting a personal Gemini API key into the sidebar (stored in PropertiesService.getUserProperties()) is quick and straightforward.

However, in Google Workspace for Education, university research laboratories, and corporate environments, three structural barriers arise:

Google AI Studio Is Restricted for Students & Non-Technical Users: In most K–12 schools and universities using Google Workspace for Education, access to Google AI Studio is disabled for student Organizational Units (OUs)—especially for under-18 students—and requiring every student, researcher, or staff member to generate and manage their own API key is a major adoption bottleneck.
Sharing a Container-Bound Google Doc Risks API Key Exposure & Wipes ScriptProperties on Copy: If a teacher or administrator simply pastes the script into a shared Google Docs template, any student with Editor access to that document can open Extensions > Apps Script and inspect the project settings. Furthermore, when Google Classroom creates individual student copies of an assignment document ("Make a copy for each student"), Google Apps Script intentionally strips all ScriptProperties from the copied files for security reasons.
Most School & Department IT Administrators Are Non-Coders: If deploying an internal tool requires editing source code to hardcode credentials or rewrite authentication flows, many school and departmental IT staff will be unable to maintain it.

2. How `v1.0.3` Solves This with a Single Unified Script

To address all three barriers without splitting the project into separate "Personal" and "Enterprise/Edu" editions, DocuMentor AI v1.0.3 introduces two core architectural upgrades in src/code.js and src/index.html.

A. Priority-Locked Dual API Key Resolution (`ScriptProperties` ➔ `UserProperties`)

In v1.0.3, the backend helper getEffectiveApiKeyInfo_() checks two storage scopes in strict priority order:

function getEffectiveApiKeyInfo_() {
  try {
    const scriptProps = PropertiesService.getScriptProperties();
    const scriptKey = scriptProps
      ? scriptProps.getProperty("GEMINI_API_KEY")
      : null;
    if (scriptKey && scriptKey.trim().length > 0) {
      return {
        apiKey: scriptKey.trim(),
        hasApiKey: true,
        apiKeySource: "script",
      };
    }
  } catch (e) {}

  try {
    const userProps = PropertiesService.getUserProperties();
    const userKey = userProps ? userProps.getProperty("GEMINI_API_KEY") : null;
    if (userKey && userKey.trim().length > 0) {
      return {
        apiKey: userKey.trim(),
        hasApiKey: true,
        apiKeySource: "user",
      };
    }
  } catch (e) {}

  return {
    apiKey: "",
    hasApiKey: false,
    apiKeySource: "none",
  };
}

Here is how this single function behaves across both environments without a single line of code modification:

🏫 Admin-Managed Mode (apiKeySource === 'script'): The IT administrator opens the Apps Script visual interface (Project Settings ⚙️ > Script Properties), clicks Add script property, and registers GEMINI_API_KEY once. Because ScriptProperties takes top priority, DocuMentor AI automatically locks into Admin-Managed Mode.
🔒 Locked Student / Organization Sidebar UI: When any student, faculty member, or employee opens the sidebar under Admin-Managed Mode, the API key input field and the Reset button are completely hidden and replaced with a locked status badge (🔒 API Key Configured (School / Organization Admin)). Furthermore, both saveApiKey() and deleteApiKey() ignore client-side overrides when apiKeySource === 'script'—meaning students cannot clear, overwrite, or inspect the organization's API key even from browser developer tools.
👤 Individual User Mode (apiKeySource === 'user' or 'none'): Individual users do not touch Project Settings ⚙️ > Script Properties, so ScriptProperties remains empty. The sidebar behaves 100% identically to previous versions: displaying the API key input box on first launch, saving the user's personal key into UserProperties, and showing 🔒 API Key Configured (Saved) with a Reset button (as shown at the top of the v1.0.3 sidebar in Section 4 below).

B. Dual Menu Registration for Both Private Marketplace Add-ons and Container-Bound Scripts (`onOpen` & `onInstall`)

When a script is published as a Google Workspace Marketplace Editor Add-on, Google Docs executes onOpen(e) in ScriptApp.AuthMode.NONE until the user interacts with the add-on, and requires menus to be registered via DocumentApp.getUi().createAddonMenu() (which places the menu under Extensions > DocuMentor AI). Conversely, personal container-bound scripts typically use createMenu('✦ DocuMentor AI') to display a top-level menu in the Google Docs toolbar.

In v1.0.3, onOpen(e) and onInstall(e) seamlessly support both execution environments in one place:

function onInstall(e) {
  onOpen(e);
}

function onOpen(e) {
  const ui = DocumentApp.getUi();
  try {
    ui.createAddonMenu().addItem("Open Dashboard", "showSidebar").addToUi();
  } catch (err) {}

  if (!e || e.authMode !== ScriptApp.AuthMode.NONE) {
    try {
      ui.createMenu("✦ DocuMentor AI")
        .addItem("Open Dashboard", "showSidebar")
        .addToUi();
    } catch (err) {}
  }
}

3. Why DocuMentor AI Is Transformative for Academia, Scientific Research, Higher Education & Engineering Training

While DocuMentor AI is a versatile writing coach for everyday business documents and K–12 classrooms, its architecture—combining Google Docs API v1 Suggestion/Comment management with Gemini's multimodal reasoning—makes it uniquely powerful for academic researchers, university laboratories, graduate students, scientific authors, and software engineering learners.

As illustrated in the workflow infographic above, DocuMentor AI operates through a three-stage multimodal pipeline designed specifically for active learning, scholarly rigor, and engineering code review:

Stage 1 — Manuscript, Code & Review History Extraction: When a researcher, student, or developer runs the tool on a Google Doc (or a highlighted section via 🎯 Proofread Selection Only), the backend inspects the active document tab via documents.get with suggestionsViewMode=PREVIEW_SUGGESTIONS_ACCEPTED and commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED. It simultaneously extracts body text and research claims, source code and scripts in any programming language (Python, JavaScript, TypeScript, Go, Java, C++, SQL, Google Apps Script, etc., line by line), structured data tables (TABLE_1, TABLE_2, ...), embedded charts and figures as binary images (VISUAL_1, VISUAL_2, ...), and both active and resolved review threads (including previously accepted or rejected inline edits and resolved comments from advisors, co-authors, or code reviewers).
Stage 2 — Gemini File API & Docs API v1 Engine: The extracted Markdown context and binary figure images are uploaded in parallel to the Gemini File API (fileData.fileUri) and analyzed by gemini-4-argon or gemini-3.8-flash. During this phase, the engine performs cross-modal and spec-to-code verification (checking whether claims, baselines, or implementation scripts match the numbers, units, and architecture diagrams in tables and figures), conducts rejection-aware history analysis (adapting its edit granularity based on what the author previously accepted or rejected), and prepares reverse-index line and phrase batch requests (startIndex descending) so multiple edits never shift downstream character offsets.
Stage 3 — Interactive Coaching in Google Docs: Rather than silently overwriting the manuscript or script, the engine delivers three complementary outputs directly inside Google Docs: 💡 Hint-Only Mode (insertComment writing and debugging hints without spoiling the rewrite), 🚀 Suggest & Coach Mode (WriteMode.SUGGEST surgical prose and code diffs paired with addCommentReply explanations), and the 🎓 Learning Summary Dialog synthesizing overall evaluation, recurring writing and coding habits, and actionable next steps.

This architecture directly addresses five critical challenges across academic research, classroom education, and software engineer training:

1. Combating "Cognitive Debt" and "Cognitive Surrender" in Academic & Student Writing

Recent cognitive science research has sounded the alarm on passive AI reliance:

MIT Media Lab Brain Study (June 2025): The study "Your Brain on ChatGPT" demonstrated that passively accepting AI-generated text induces "cognitive debt," measurably reducing neural connectivity and mental engagement (Ref).
CMU, Wharton & MIT Studies (2026): Subsequent research highlighted the "shortcut trap"—where even 10 minutes of AI reliance reduces subsequent independent problem-solving performance by 20% (Ref)—and "cognitive surrender," where fluent AI outputs create an illusion of competence that stops students from thinking critically (Ref).
Nikkei XTECH Survey (October 2026): In this survey, 42.1% of generative AI users cited "decline in thinking ability due to AI dependency" as their #1 concern (Ref).

In universities and schools, faculty often hesitate to permit AI tools because conventional rewriters turn students into passive copy-pasters. DocuMentor AI flips this dynamic by requiring authors to either formulate their own revisions from anchored coaching hints (💡 Hint-Only Mode) or critically evaluate each transparent diff paired with its grammatical/logical reason (🚀 Suggest & Coach Mode).

2. True Cross-Modal Consistency Verification (`Prose ⇄ Tables ⇄ Figures`) for Research Papers

Academic manuscripts—such as journal articles, conference papers, theses, and grant proposals—never consist of prose alone. One of the most common reasons peer reviewers flag scientific drafts is cross-modal inconsistency:

Mismatched Baselines & Metrics: Numbers or percentages cited in the Results text do not match the values or baselines in Table 1 or Figure 1.
Inconsistent Units & Labels: Axis labels, units, or terminology in a bar chart or architecture diagram (Execution Time (Minutes)) differ from the column headers in a table (Task Time).
Uncited Visuals: Figures and tables are inserted into the manuscript without being explicitly cited or interpreted in the narrative.

Because DocuMentor AI uploads the manuscript's structured Markdown and binary figure images in parallel to the Gemini File API, gemini-4-argon inspects the actual visual pixels of your plots alongside your tables and prose—proposing inline cell edits (WriteMode.SUGGEST) and attaching anchored review comments (insertComment) directly onto every figure and table.

3. Distilling Co-Author, Advisor & Peer-Review History into Long-Term Learning (`INCLUDE_RESOLVED_HISTORY`)

In academic labs and graduate programs, a Google Doc often accumulates dozens of inline suggestions and comment threads from a principal investigator (PI), thesis advisor, or co-authors. Once a student clicks Accept on the advisor's edits or Resolve on comment threads, that valuable pedagogical feedback normally disappears into the document's history.

With DocuMentor AI, calling documents.get with commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED extracts both open review threads and resolved review history (RESOLVED, ACCEPTED, REJECTED):

Step 1 History Ledger: Renders an expandable 📜 View Resolved Review History ledger right in the sidebar showing every accepted/rejected edit and resolved comment thread.
Rejection-Aware Adaptive Proofreading: When 📜 Include Resolved Review History is enabled during proofreading, Gemini respects the author's prior rejections (for instance, switching from full-sentence rewrites to surgical phrase-level edits if the author previously rejected broad rewrites).
Retrospective Learning Summary: By turning ON 📜 Include Resolved Review History and clicking 🎓 Generate Learning Summary from Suggestions & Comments, graduate students and researchers can synthesize their advisor's or co-authors' entire review pass—even after all threads are resolved—into a structured Writing Coach & Learning Summary.

4. Protecting Unpublished Research Data & Scaling Across Classrooms

For universities and schools deploying DocuMentor AI via ScriptProperties, linking the institution's Google Cloud Billing account (Paid Tier 1+) to the Gemini API project provides two essential guarantees:

Strict Academic & Student Data Privacy: Under Google's Gemini API Terms of Service for paid/billed projects, submitted manuscripts, tables, and unpublished research figures are never used to train or improve Google models—preserving academic originality and student privacy. Additionally, DocuMentor AI automatically deletes all temporary files from the Gemini File API inside a finally block (deleteGeminiFiles_) immediately after each request.
High Concurrent Throughput & Distributed GAS Quotas: Paid Tier rate limits allow an entire classroom of 30–40 students or a full research department to run multimodal proofreading simultaneously without hitting Free Tier RPM bottlenecks, while Google Apps Script UrlFetchApp quotas are counted per active student/researcher account (20,000–100,000 calls/day per user) rather than sharing a single user's quota.

5. Beyond Prose: Why DocuMentor AI Is Ideal for Multi-Language Script Learning, Code Review & Engineer Training

While designing and testing DocuMentor AI, I realized that its core mechanism is not limited to natural-language essays or academic papers—it is equally powerful for coaching programming scripts across any language (Python, JavaScript, TypeScript, Go, Java, C++, Rust, SQL, Bash, Google Apps Script, and more).

Just as passive AI text rewriting leads to "cognitive surrender" in essay writing, software engineering education, university computer science courses, and corporate DX (citizen-developer) training face an identical crisis: "vibe coding"—where beginners and junior engineers blindly copy and paste AI-generated code without understanding what was wrong in their original script, why it failed at runtime, or how the underlying language or API actually works.

When we examine both the pedagogical workflow and the internal implementation of src/code.js, three reasons make DocuMentor AI uniquely suited for multi-language script learning and educational code reviews inside Google Docs:

1. Transforming Passive Copy-Pasting into Active, Language-Agnostic Engineering Mentorship: Instead of handing over a rewritten file that replaces the learner's entire script at once, DocuMentor AI supports two active-learning code review modes for any programming language. In 💡 Hint-Only Mode (insertComment), it acts like a Socratic senior engineer mentor—highlighting the buggy, inefficient, or insecure line of code and explaining the root cause (e.g., an off-by-one error, SQL injection risk, memory leak, unclosed resource, or API misuse) so the learner can debug and refactor the line themselves first. In 🚀 Suggest & Coach Mode (WriteMode.SUGGEST + addCommentReply), it acts like an educational GitHub Pull Request inline diff—crossing out the problematic line, proposing the idiomatic replacement in that target language inline, and attaching a reply with the 💡 Reason for Revision and 🎓 Learning Point, followed by a 🎓 Writing Coach & Learning Summary that diagnoses recurring coding habits across the entire script.
2. High Technical Affinity with DocuMentor AI's Line-Block & Reverse-Index Engine (src/code.js): Why does Google Docs inline suggestion mode work so cleanly on source code regardless of the programming language? When any script is pasted into Google Docs with normal line breaks (Enter), Step 1 extracts each line of code as an independent paragraph block in editableBlocks ([Block N (Body)]). In Step 2, Gemini's strict schema rule (each "originalText" MUST be an exact, character-for-character substring found within "Target Editable Settled Text Blocks" without newlines) naturally guides the model to target self-contained, single-line bugs and anti-patterns. Then, in Step 3 (step3_buildRequestBody()), all matched code lines are sorted in reverse character-index order (b.startIndex - a.startIndex) and updated via deleteContentRange + insertText under WriteControl.writeMode = "SUGGEST". As a result, indentation (even in whitespace-sensitive languages like Python!) and character offsets never shift, and clicking ✅ Accept All Suggestions immediately produces a 100% syntactically valid, runnable script that can be copied straight into an IDE or code editor!
3. Multimodal Specification-to-Code Verification (Architecture Diagram + API Spec Table + Script): Traditional code linters and IDE extensions only see raw text files. Because DocuMentor AI is powered by the Gemini File API's multimodal pipeline, an instructor, tech lead, or engineer can place a system architecture diagram (Figure 1), an API specification or database schema table (Table 1), and the implementation code (in Python, TypeScript, Go, GAS, etc.) inside a single Google Doc—allowing Gemini to simultaneously review the code for bugs and verify whether the implementation accurately matches the architecture diagram and specification table!

4. Live Demonstration (`v1.0.3`): Inside the Sidebar Dashboard, Prose Modes & Interactive Code Review

To see how DocuMentor AI v1.0.3 works in practice across both multimodal technical manuscripts (body text, Table 1, and Figure 1) and programming scripts (using a beginner Google Apps Script as our concrete code review example), let's first look at the v1.0.3 Sidebar Control Center, and then walk through three live execution cases.

Inside the `v1.0.3` Sidebar Dashboard (`sidebar_v103.jpg`)

As shown in sidebar_v103.jpg above, the entire workflow is controlled from a clean, four-part sidebar inside Google Docs:

1. Header & Bilingual UI Switcher (EN / JA): Displays the version badge (v1.0.3 • AI Proofreading Coach), an info modal trigger (ⓘ), and a one-click language toggle (EN / JA) that switches both the sidebar labels and the language of Gemini's coaching explanations and learning summaries.
2. ⚙️ AI Engine & API Settings: Displays the API key status badge and model selector (gemini-4-argon (High Precision) vs. gemini-3.8-flash (Fast & Balanced)). In Individual Mode (UserProperties), this card shows 🔒 API Key Configured (Saved) with a Reset link as pictured above; in School/Organization Mode (ScriptProperties), it automatically locks to 🔒 API Key Configured (School / Organization Admin) and hides the Reset link.
3. ✍️ Proofreading Scope & Controls: Houses the three independent pedagogical toggles—🎯 Proofread Selection Only (here OFF to inspect the entire active tab), 💡 Hint-Only Mode (Comment Without Rewrite) (here turned ON with an amber border), and 📜 Include Resolved Review History (here turned ON with an emerald border)—followed by custom instructions, quick preset chips (#Concise & Logical, #Business Tone, #Tables & Charts, #Grammar & Flow), and action buttons (💡 Run Proofreading (Hint-Only Comments), 🎓 Generate Learning Summary from Suggestions & Comments, 📝 Generate Initial Text from Prompt, ✅ Accept All Suggestions, 🧹 Clear All Suggestions, and 🗑️ Clear All Comments). Notice how toggling ON 💡 Hint-Only Mode dynamically updates the primary button label from 🚀 Run Proofreading (Suggest & Coach) to 💡 Run Proofreading (Hint-Only Comments).
4. 📊 PROCESS DASHBOARD (Steps 1–4): Tracks the real-time 4-stage pipeline (1 Fetch Text, Tables & Figures, 2 Generate AI Proofreading & Coaching, 3 Build Suggestion Request Body, and 4 Apply Suggestions & Comments), shown here in its initial Waiting state right before clicking run.

Choosing the Right Model: `Gemini 3.8 Flash` vs. `Gemini 4 Argon`

In the ⚙️ AI Engine & API Settings card of the sidebar, you can switch between gemini-3.8-flash (Fast & Balanced) and gemini-4-argon (High Precision) at any time. Because DocuMentor AI supports both natural-language manuscript proofreading and multi-language code review, choosing the right model for your current stage of work maximizes both speed and analytical depth.

The table below summarizes the recommended decision criteria across writing, research, and software engineering workflows:

Scenario / Use Case	Domain	Recommended Model	Why & Key Selection Criteria
1. Typo, Spelling & Grammar Check	✍️ Prose	⚡ `Gemini 3.8 Flash` (Fast & Balanced)	Fixing typos, spelling mistakes, and clear grammatical errors relies primarily on pattern recognition—making Flash's high speed and low token cost the optimal choice.
2. Routine Code Refactoring	💻 Code	⚡ `Gemini 3.8 Flash` (Fast & Balanced)	Standardizing naming conventions, adding comments/docstrings, and rewriting simple functions without complex algorithmic changes complete almost instantaneously with Flash.
3. Rapid Iterative Drafting & Interactive Checks	✍️ Prose / 💻 Code	⚡ `Gemini 3.8 Flash` (Fast & Balanced)	When actively drafting or iterating in the editor and wanting fast, rhythmic feedback or brainstorming without breaking your creative flow, Flash's ultra-low latency provides a stress-free experience.
4. First-Pass Triage of Large Documents or Long Scripts	✍️ Prose / 💻 Code	⚡ `Gemini 3.8 Flash` (Fast & Balanced)	Ideal for cost-effectively screening long manuscripts or large scripts to surface broad errors and recurring issues in a single initial pass.
5. Logical Consistency in Academic Papers, Contracts & Multimodal Figures	✍️ Prose & 🖼️ Visuals	🧠 `Gemini 4 Argon` (High Precision)	Best when deep contextual reasoning is required to detect contradictions across claims, flawed logical progressions, subtle loopholes in legal/contractual phrasing, or cross-modal mismatches between body text, tables, and figures.
6. Complex Algorithm & Data Structure Review	💻 Code	🧠 `Gemini 4 Argon` (High Precision)	Shines in code reviews that require deep analytical thinking—such as optimizing time and space complexity, designing advanced data structures, and verifying subtle edge-case bugs.
7. Security Auditing & Vulnerability Detection	💻 Code	🧠 `Gemini 4 Argon` (High Precision)	Ideal for deeply tracing execution paths to uncover concurrency bugs (race conditions), injection vulnerabilities, credential exposure, or subtle security flaws hidden in source code.
8. Nuanced Tone, Style & Psychological Audience Adaptation	✍️ Prose	🧠 `Gemini 4 Argon` (High Precision)	Powerful for executing abstract, high-level editorial instructions beyond surface proofreading—such as rewriting text to achieve a specific psychological effect or persuasive tone tailored to a target audience.

💡 Practical Two-Pass Workflow Tip: For long academic papers or complex scripts, start with gemini-3.8-flash for a fast, low-cost First-Pass Triage (cleaning up typos, basic grammar, and naming conventions), and then switch to gemini-4-argon for your Deep Second Pass (verifying thesis/contract logic, cross-checking Table 1 and Figure 1, or auditing algorithm complexity and security vulnerabilities).

Case A: Running "💡 Hint-Only Mode" (Active-Recall Coaching Without Spoiling the Answer)

With the sidebar configured exactly as shown in sidebar_v103.jpg above (gemini-4-argon (High Precision), 💡 Hint-Only Mode ON, and 📜 Include Resolved Review History ON), we click 💡 Run Proofreading (Hint-Only Comments):

Look closely at what happens across the three panes in hint_only_mode_result.jpg:

Zero Forced Rewrites on the Document Canvas (Left Pane): Not a single word of the author's manuscript is crossed out or overwritten with green suggestion text. Instead, phrases requiring attention—such as "is basically a coding platform that is provided by Google, and it is made based on the JavaScript language.", "The most biggest advantage of using GAS is because", "connect and integrate", "boring daily routine works.", "Target App" in Table 1, and Figure 1—are highlighted in yellow as anchored Google Docs comments (insertComment).
Socratic Coaching Comments in the Comment Stream (Center Pane): Looking at the expanded top comment card ([DocuMentor AI | 💡 Hint Mode: Conciseness]), DocuMentor AI identifies the exact 🎯 Flagged Phrase, explains the 💡 Issue to Check ("The conversational filler word 'basically' and the passive clauses ('that is provided by', 'and it is made based on') make this opening technical definition overly wordy"), and provides a 🎓 Coaching Hint (Try Rewriting Yourself!) ("Try removing the filler adverb and tightening the two passive clauses into concise modifiers (for example, using a compound adjective for the language and a past participle phrase for the provider)").
On-Demand Reference Rewrites & Learning Summary (Right Sidebar): Students or researchers can attempt their own revision in the document first, and only click 👁️ Show Reference Rewrite in the sidebar if they get stuck.

Immediately after Hint-Only Mode finishes, DocuMentor AI pops up the 🎓 Writing Coach & Learning Summary modal dialog (which can be re-opened anytime via 📖 Re-open Latest Learning Summary Dialog). Here is the exact summary output produced for this Hint-Only session:

[🎓 Writing Coach & Learning Summary (DocuMentor AI v1.0.3)]

■ 📋 Overall Manuscript Evaluation
This manuscript clearly outlines the core strengths of Google Apps Script (GAS) and how it integrates with Google Workspace and the Gemini AI API. However, several grammatical errors, redundant modifiers, uncountable noun pluralizations, and overly conversational expressions remain in the body text. Additionally, the table and Figure 1 contain valuable quantitative comparisons (such as the 120-minute manual baseline and 96% time savings) that should be better aligned with the surrounding narrative. Because Hint-Only Mode is active, each flagged phrase includes a clear explanation of the underlying issue and a constructive coaching hint so you can practice revising the sentences yourself.

■ 💡 What Was Flagged & Hinted
Flagged grammatical errors (double superlatives, uncountable nouns like 'software' and 'work', and 'the advantage is because'), redundant word pairings ('connect and integrate', 'many various'), and awkward direct translations ('there is a merit that', 'learning hurdle is low', 'very recommended'). Also provided review comments on aligning Table 1 and Figure 1 with the main text.

■ 🔍 Areas for Improvement & Writing Habits
1. Stacking redundant modifiers or intensifiers (e.g., 'most biggest', 'many various', 'super simple', 'totally... at all'). 2. Pluralizing uncountable nouns ('softwares', 'routine works'). 3. Using literal translations of non-English idioms ('there is a merit that', 'learning hurdle is low') instead of natural English collocations.

■ 🌱 Actionable Advice for Future Writing
1. Check noun countability: remember that 'software' and 'work' (meaning labor) are uncountable; use 'software' and 'tasks' instead. 2. Pair 'The advantage is...' with a 'that'-clause or noun phrase rather than 'because'. 3. Use standard collocations like 'gentle learning curve' and 'highly recommended', and explicitly cite your figures and tables in the body text.

Notice how the Hint-Only Learning Summary does not merely list isolated typos—it diagnoses the writer's underlying structural habits (stacking redundant intensifiers, pluralizing uncountable nouns like 'softwares' and 'works', and translating non-English idioms literally like 'there is a merit that' or 'learning hurdle is low') and reminds the author to align the quantitative metrics in Table 1 (120-minute manual baseline) and Figure 1 (96% time savings) with the main narrative.

Case B: Running "🚀 Suggest & Coach Mode" with Resolved Review History (Rejection-Aware Surgical Edits)

Next, let's see what happens when we turn OFF 💡 Hint-Only Mode, keep 📜 Include Resolved Review History turned ON, and click 🚀 Run Proofreading (Suggest & Coach):

Examining suggest_mode_result.jpg reveals three powerful capabilities working together:

Rejection-Aware Surgical Edits (WriteMode.SUGGEST) on the Canvas (Left Pane): In an earlier review pass on this document, full-sentence rewrites had been rejected by the author (stored in the document's resolved history). Because 📜 Include Resolved Review History is active, DocuMentor AI detects that preference and automatically shifts from broad full-sentence rewrites to surgical, phrase-level inline suggestions that preserve the author's natural voice! Specifically, it proposes targeted replacements for "The most biggest advantage of using GAS is because" ➔ "The biggest advantage of using GAS is that", "connect and integrate with many various" ➔ "integrate with various", "boring daily routine works." ➔ "repetitive daily tasks.", "special softwares" ➔ "special software", "There is a merit that you can" ➔ "A key benefit is that you can", "learning hurdle is low," ➔ "learning curve is gentle,", and "is very recommended." ➔ "is highly recommended.", alongside anchored cross-modal review comments (insertComment) on Table 1 ("Target App") and Figure 1.
Native Suggestion Cards Paired with Educational Replies (Center Pane): In the Google Docs margin, every native Replace: ... with ... suggestion card is automatically enriched with an educational reply via addCommentReply. For example, on the first card (Replace: “The most biggest advantage of using GAS is because” with “The biggest advantage of using GAS is that”), the reply explains both the 💡 Reason for Revision ("Corrects the double superlative ('most biggest' -> 'biggest') and fixes the ungrammatical construction 'The advantage... is because' by replacing 'because' with 'that'") and the transferable 🎓 Learning Point ("Never combine 'most' with an '-est' superlative adjective, and always follow nouns like 'advantage' or 'reason' + 'is' with a 'that'-clause rather than 'because'").
Granular Accept / Reject Control (Right Sidebar & Native Cards): The author can review and accept or reject each suggestion individually or in bulk from the sidebar while reading the exact rationale behind every edit.

Here is the exact 🎓 Writing Coach & Learning Summary generated after running Suggest & Coach Mode:

[🎓 Writing Coach & Learning Summary (DocuMentor AI v1.0.3)]

■ 📋 Overall Manuscript Evaluation
Your manuscript provides a clear, well-structured introduction to Google Apps Script (GAS), effectively combining explanatory text, a summary table (Table 1), and a composite architecture and benchmark figure (Figure 1). Because previous full-sentence rewrites were rejected in favor of targeted, phrase-level improvements, this review focuses on surgical edits that preserve your natural voice while correcting specific grammatical errors (such as double superlatives, uncountable nouns, and redundant pairings) and improving alignment between the text, Table 1, and Figure 1.

■ 🛠️ What Was Revised
Proposed targeted, phrase-level revisions to fix grammatical errors ('most biggest', 'advantage... is because', 'softwares', 'routine works'), eliminate tautologies ('connect and integrate with many various'), refine idiomatic collocations ('gentle learning curve', 'highly recommended'), and improve data consistency across Table 1 and Figure 1.

■ 🔍 Areas for Improvement & Writing Habits
Two recurring habits appear in the draft: (1) stacking redundant modifiers or double intensifiers ('most biggest', 'connect and integrate', 'many various', 'totally... at all'), and (2) pluralizing uncountable English nouns ('softwares', 'works') or translating Japanese idioms literally ('There is a merit that', 'learning hurdle is low', 'very recommended').

■ 🌱 Actionable Advice for Future Writing
1. Treat 'software' and 'work' (meaning labor/duties) as uncountable nouns; use 'software' and 'tasks' instead.
2. Pair 'The advantage is...' with 'that' rather than 'because', and never combine 'most' with '-est' adjectives.
3. Ensure baseline numbers and service labels in your tables and figures (such as the 120-minute manual baseline and Gmail/GmailApp) match across all elements.

Look at the second sentence of ■ 📋 Overall Manuscript Evaluation above:

"Because previous full-sentence rewrites were rejected in favor of targeted, phrase-level improvements, this review focuses on surgical edits that preserve your natural voice while correcting specific grammatical errors..."

This demonstrates why combining commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED with Gemini's multimodal reasoning is such a leap forward: DocuMentor AI learns from what the writer accepts and rejects within the document's history, adapting its coaching style to respect the writer's voice while still catching cross-modal discrepancies (such as matching the 120-minute manual baseline and Gmail/GmailApp labels across the prose, Table 1, and Figure 1).

Case C: Beyond Prose — Interactive Multi-Language Code Review & Script Coaching (`code_review_mode_result.jpg`)

Finally, let's test the new use case I conceived for DocuMentor AI: coaching programming scripts and conducting line-by-line code reviews inside Google Docs. While this workflow supports any programming language (Python, JavaScript, TypeScript, Go, Java, C++, SQL, etc.), here we demonstrate it using a beginner Google Apps Script snippet (sendDailyReport) pasted into Google Docs. It represents a common automation task—reading rows from a Google Sheet, summarizing them with the Gemini API, and emailing the summary—written with typical beginner bugs, security risks, and API misuses:

// Sample Beginner Google Apps Script: Summarize spreadsheet tasks with Gemini and send an email
function sendDailyReport() {
  // 1. Set the Gemini API key and get the target spreadsheet tab
  var apiKey = "AIzaSyD-1234567890abcdef_HARDCODED_KEY";
  var sheet = SpreadsheetApp.getActiveSpreadsheet().getActiveSheet();

  // 2. Read all task rows from the sheet (Rows 2 to 50, Columns A to C)
  var data = sheet.getRange("A2:C50").getValue();

  // 3. Stop execution if the retrieved task data is empty
  if (data == "") {
    Logger.log("No task data found.");
    return;
  }

  // 4. Call the Gemini API using UrlFetchApp to summarize today's tasks
  var url =
    "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=" +
    apiKey;
  var payload = {
    contents: [
      { parts: [{ text: "Summarize these tasks: " + JSON.stringify(data) }] },
    ],
  };
  var response = UrlFetchApp.fetch(url, { method: "post", payload: payload });
  var result = JSON.parse(response);

  // 5. Send the generated summary to the manager via email
  MailApp.sendEmail(
    "manager@example.com",
    "Daily Task Summary",
    result.candidates[0].content.parts[0].text,
  );
  Logger.log("Successfully sent the daily report!");
}

Next, we entered the following prompt into Additional Proofreading Instructions in the sidebar and clicked 🚀 Run Proofreading (Suggest & Coach):

Review this Google Apps Script code for bugs, GAS API misuse, security risks, and modern V8 JavaScript best practices, proposing line-by-line code fixes.

Here is the resulting Google Docs canvas and sidebar after execution (code_review_mode_result.jpg):

Look at what code_review_mode_result.jpg achieves across all three panes:

1. Security Fix (PropertiesService Instead of Hardcoded API Keys): On line 4, DocuMentor AI crosses out var apiKey = "AIzaSyD-1234567890abcdef_HARDCODED_KEY"; and suggests const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");—teaching the developer never to hardcode credentials in source files.
2. GAS Range API Bug Fix (getValues() + Blank-Row Filtering Instead of getValue()): On line 8, beginners frequently call .getValue() (singular) on a multi-cell range like "A2:C50", which silently ignores every cell except A2. DocuMentor AI replaces var data = sheet.getRange("A2:C50").getValue(); with const data = sheet.getRange("A2:C50").getValues().filter(row => row.some(cell => cell !== "")); and updates if (data == "") on line 11 to if (data.length === 0). Look at the expanded comment reply in the center pane ([DocuMentor AI | Bug Fix (GAS API Misuse)]): it clearly explains what was wrong and why ("getValue() only returns the value of the top-left cell (A2), ignoring the rest of A2:C50. getValues() retrieves the entire 2D array of rows and columns, and filtering out completely blank rows prevents sending empty rows to the Gemini API") and states the 🎓 Learning Point ("Use getValues() instead of getValue() when reading a range that spans multiple cells, and filter out empty rows before processing").
3. UrlFetchApp.fetch & HTTPResponse Bug Fixes: On lines 19–20, calling UrlFetchApp.fetch(url, { method: "post", payload: payload }) with a raw object sends form-encoded data instead of JSON, and calling JSON.parse(response) directly on a GAS HTTPResponse object fails at runtime. DocuMentor AI suggests adding contentType: "application/json" with payload: JSON.stringify(payload) and parsing via JSON.parse(response.getContentText()).
4. Defensive Optional Chaining (?.) & Modern V8 Syntax (const, Template Literals, console.log): On line 23, it replaces unprotected deep property access (result.candidates[0].content.parts[0].text) with const summary = result.candidates?.[0]?.content?.parts?.[0]?.text || "No summary generated."; MailApp.sendEmail("manager@example.com", "Daily Task Summary", summary); and upgrades legacy var and Logger.log() calls to V8 const, template literals, and console.log(). Crucially, if the learner clicks ✅ Accept All Suggestions, the resulting document is a 100% syntactically valid, runnable Google Apps Script!

And here is the exact 🎓 Writing Coach & Learning Summary generated for this Google Apps Script review:

[🎓 Writing Coach & Learning Summary (DocuMentor AI v1.0.3)]

■ 📋 Overall Manuscript Evaluation
This Google Apps Script snippet provides a clear high-level workflow for reading spreadsheet tasks, summarizing them with the Gemini API, and sending an email report. However, it contains several critical runtime bugs, a major security vulnerability (hardcoded API key), incorrect Google Apps Script API methods (such as using `getValue()` for a multi-cell range and improperly configuring `UrlFetchApp.fetch` for JSON), and outdated ES5 `var` declarations. Applying the line-by-line fixes below will make the script secure, functional, and compliant with modern V8 JavaScript standards.

■ 🛠️ What Was Revised
Replaced the hardcoded API key with `PropertiesService`, fixed `getValue()` to `getValues()` for multi-row range reading, updated the empty-data check to inspect the 2D array properly, corrected the Gemini model name and `UrlFetchApp` JSON payload configuration, fixed `HTTPResponse` parsing with `getContentText()`, added optional chaining for safer response access, and modernized variable declarations from `var` to `const`.

■ 🔍 Areas for Improvement & Writing Habits
The script shows common beginner pitfalls in Google Apps Script: confusing single-cell and multi-cell `Range` methods (`getValue` vs. `getValues`), assuming `UrlFetchApp.fetch` automatically serializes JavaScript objects as JSON and returns a string directly, hardcoding sensitive credentials in source code, and using legacy `var` syntax instead of V8's `const`/`let`.

■ 🌱 Actionable Advice for Future Writing
1. Always store API keys in Script Properties (`PropertiesService.getScriptProperties()`). 2. When working with multi-cell ranges, use `getValues()` and remember it returns a 2D array (`[][]`) even for empty cells. 3. When calling REST APIs with `UrlFetchApp`, always set `contentType: 'application/json'`, stringify the payload (`JSON.stringify()`), and call `.getContentText()` on the response before parsing.

Instead of blindly copying a rewritten block of code from a chatbot without knowing what changed, an aspiring engineer or computer science student gets an interactive line-by-line code review right inside Google Docs—learning what was broken, why it failed, and how to write production-grade Google Apps Script in the future.

5. Comparison: Individual Mode vs. School, Organization & Academic Lab Mode

Both modes run from the exact same three files in src/:

Aspect	👤 Individual Mode (Personal Setup)	🏫 School, Organization & Academic Lab Mode
Target Users	Individual writers, independent researchers, developers, bloggers.	K–12 schools, university classes, academic research labs, corporate teams.
Deployment Type	Container-bound script inside a Google Doc (`Extensions > Apps Script`).	Standalone script published as a Private (Domain-Internal) Google Workspace Marketplace Editor Add-on.
Code Changes Required	None (copy & paste `src/` as-is).	None (copy & paste the exact same `src/` files as-is).
Where the Gemini API Key Is Stored	`PropertiesService.getUserProperties()` (entered by the user in the sidebar UI).	`PropertiesService.getScriptProperties()` (entered once by the IT Admin in Project Settings ⚙️ > Script Properties).
Sidebar API Key UI	Shows input box on first run; once saved, shows `🔒 API Key Configured (Saved)` + Reset button.	Automatically locked: shows `🔒 API Key Configured (School / Organization Admin)` with no input box and no Reset button.
API Key Security	Private to the individual user's Google account.	100% isolated: Students/end users cannot open `Apps Script`, cannot view `ScriptProperties`, and never need Google AI Studio.
Document Availability	Available in the Google Doc where the script was pasted.	Available in every Google Doc across the school/lab domain (installed automatically via Google Admin Console for OUs).
Step-by-Step Guide	👉 `INSTALL_INDIVIDUAL.md`	👉 `INSTALL_ORGANIZATION.md`

6. Quick Walkthrough of the Two Setup Workflows

Workflow A: Individual Setup (3 Minutes)

Open Apps Script: Open your Google Document and click Extensions > Apps Script.
Paste the Source Files: Enable appsscript.json in Project Settings (⚙️), and copy src/appsscript.json, src/code.js (into Code.gs), and src/index.html into the editor.
Save Your Personal Key: Reload the Google Doc, click ✦ DocuMentor AI > Open Dashboard, paste your Gemini API key into the sidebar, and click Save. For detailed instructions, see INSTALL_INDIVIDUAL.md.

Workflow B: Zero-Code School, University & Organization Rollout (10 Minutes for IT Admins)

Create a Standalone Script & Set ScriptProperties: Open script.google.com, create a new project, and paste src/appsscript.json, src/code.js, and src/index.html. Then open Project Settings (⚙️) > Script Properties, click Add script property, set Property = GEMINI_API_KEY and Value = your organization's Gemini API key, and click Save.
Publish as a Private (Internal) Marketplace Add-on: Link a standard GCP project number in Apps Script Project Settings (⚙️) and create an Add-on deployment (Deploy > New deployment). In the GCP Console, enable Google Docs API and Google Workspace Marketplace SDK, set the OAuth Consent Screen to Internal, and configure the Google Workspace Marketplace SDK with Visibility: Private (domain-only, requiring zero public review wait time).
Install for Student / Researcher Organizational Units: In the Google Workspace Admin Console (admin.google.com), go to Apps > Google Workspace Marketplace apps > Apps list > Install app > Internal apps, select DocuMentor AI, and perform an Admin install for your target Organizational Units (e.g., /Students, /GraduateLab, or domain-wide). Students and researchers can immediately open any Google Doc and launch Extensions > DocuMentor AI > Open Dashboard with the organization's API key pre-configured and locked. For the complete IT Administrator checklist and prerequisites, see INSTALL_ORGANIZATION.md.

Summary

By evolving DocuMentor AI (v1.0.3) to support both Individual Mode (UserProperties) and School, Organization & Academic Mode (ScriptProperties + Private Google Workspace Marketplace Add-on) within a single codebase—and combining 💡 Hint-Only Mode, 🚀 Rejection-Aware Suggest & Coach Mode, 💻 Interactive Code Review & Script Coaching, and 🎓 Retrospective Learning Summaries—anyone from an independent writer, software engineer, or academic researcher to a school IT administrator can deploy a safe, multimodal, pedagogical writing and coding coach inside Google Docs without modifying a single line of code.

All updated source code, sample multimodal manuscripts, and separated installation guides are available on GitHub:

GitHub Repository: https://github.com/tanaikech/DocuMentorAI
Previous Article (Part 1): Building a Multimodal, Suggestion-Based AI Writing Coach with Gemini and Google Docs
👤 Individual Setup Guide: INSTALL_INDIVIDUAL.md
🏫 School, University & Organization Setup Guide: INSTALL_ORGANIZATION.md

Building a Multimodal, Suggestion-Based AI Writing Coach with Gemini and Google Docs

Tanaike — Fri, 23 Oct 2026 05:52:48 +0000

When we use generative AI to proofread our daily writing—whether technical reports, business proposals, or blog posts—it is easy to fall into the habit of simply copying and pasting AI-rewritten text without reflecting on what was changed or why. While that fixes the immediate draft, it rarely helps us grow as writers.

Recently, Google introduced powerful new capabilities to programmatically manage comments and suggestions across Google Docs, Sheets, and Slides via the Google Workspace APIs (see the official guide: Work with suggestions and comments in the Google Docs API).

In this article, I introduce DocuMentor AI, an open-source Google Docs add-on built with Google Apps Script, the Google Docs API (v1), and the Gemini API (gemini-3.8-flash / gemini-4-argon). Instead of overwriting your manuscript directly, DocuMentor AI uses the new WriteControl.writeMode = "SUGGEST" and comment management APIs (addCommentReply, insertComment, acceptSuggestion, rejectSuggestion, and deleteComment) to turn Google Docs into an interactive, multimodal writing coach for continuous self-learning. As shown in the overview infographic above, the system connects three cohesive stages: 1. Scope & Multimodal Input (analyzing the entire active tab or a highlighted selection across body text, tables, and embedded figures/charts), 2. Gemini AI & Docs API Engine (combining gemini-3.8-flash / gemini-4-argon multimodal reasoning with temporary Gemini File API uploads and Google Docs API v1 batch operations), and 3. Interactive Self-Learning Output (delivering inline suggested edits with attached Reason and Learning Point replies, anchored figure/table review comments, and a pop-up Writing Coach & Learning Summary dialog). Furthermore, because I also wanted to verify the true capabilities of Gemini 4 Argon, the DocuMentor AI application itself was built using Gemini 4 Argon, while also integrating gemini-4-argon as its high-precision multimodal proofreading and coaching engine.

GitHub Repository: https://github.com/tanaikech/DocuMentorAI

Purpose, Motivation & Addressing the "AI-Induced Cognitive Offloading" Problem

Purpose of Development & Effectiveness Against AI-Induced "Thought Stopping"

DocuMentor AI was developed to break away from the conventional paradigm of generative AI proofreading—which focuses solely on "efficiency by directly replacing the final text"—and instead achieve "preserving user agency and maximizing learning outcomes."

In recent years, "thought stopping" (cognitive offloading) and the decline of critical thinking abilities caused by over-reliance on AI have become pressing societal challenges. For example, a June 2025 brain study by the MIT Media Lab ("Your Brain on ChatGPT") demonstrated the risk of "cognitive debt," showing that continuously and passively accepting AI-generated outputs reduces brain activity and neural connectivity (Ref). Furthermore, entering 2026, research from institutions such as Carnegie Mellon University, the Wharton School (University of Pennsylvania), and MIT, along with related reports, have highlighted phenomena across education and business including the "shortcut trap"—where even 10 minutes of AI reliance reduces subsequent independent problem-solving and logical thinking performance by 20% (Ref)—and "cognitive surrender," where reading fluent AI responses creates a false illusion of understanding and leads students and professionals to stop thinking critically for themselves (Ref).

DocuMentor AI fundamentally solves these challenges by leveraging Google Docs' native Suggestion and Comment features to visualize the thought process and rationale (Why—which part was revised, how, and why) rather than overwriting the author's text. Because the user must actively judge whether to accept or reject each proposed revision, critical thinking is naturally triggered instead of blindly accepting AI output. According to a survey reported by Nikkei XTECH in October 2026, the #1 concern among generative AI users (42.1%) is the "decline in thinking ability due to AI dependency" (Ref). By transforming AI from a mere "ghostwriter" into a "side-by-side personal tutor," DocuMentor AI directly addresses this concern and empowers users to cultivate autonomous writing skills and a continuous growth mindset.

Technical Inspiration

When I read the following three insightful articles recently published by Romin Irani demonstrating the new Google Docs API comment and suggestion features, I realized that these capabilities could be applied not only to automated document review, but also as a self-directed learning environment where writers can inspect every suggested revision alongside its underlying rationale:

At the same time, I wanted to evaluate and confirm the real-world power of Gemini 4 Argon. Therefore, I built the entire DocuMentor AI application using Gemini 4 Argon—from designing the 4-stage pipeline, resolving bottom-to-top UTF-16 character indices across unsettled suggestions, and orchestrating the new Google Docs API v1 suggestion/comment endpoints, to crafting the interactive sidebar dashboard (src/code.js and src/index.html)—and also incorporated gemini-4-argon directly into the add-on as the high-precision model for multimodal proofreading and coaching.

Inspired by these articles and powered by Gemini 4 Argon, I designed DocuMentor AI around four core pillars:

1. Non-Destructive, Transparent AI Editing (`WriteMode.SUGGEST`)

Traditional AI writing tools either overwrite your text directly or force you to switch back and forth between an external chat window and your document. By programmatically submitting edits in Google Docs' native Suggest Mode (writeControl: { writeMode: "SUGGEST" }) and attaching educational replies (addCommentReply) directly to each suggestion thread, authors retain 100% editorial control to accept or reject every proposed revision.

2. True Multimodal Manuscript Understanding (Text, Tables & Figures)

Real-world documents—especially academic papers and technical reports—are rarely plain text alone; they combine prose, structured tables, and numerous visual charts or diagrams. DocuMentor AI extracts document tables as structured Markdown, fetches embedded figures and charts as binary images, temporarily uploads them via the Gemini File API, passes their file URIs (fileData.fileUri) to Gemini, and automatically deletes the uploaded files immediately after content generation to keep the environment completely clean. As a result, Gemini can propose inline phrasing edits inside table cells, verify numerical alignment between body text and charts, and attach anchored improvement comments (insertComment) directly to tables (TABLE_1, etc.) and figures (VISUAL_1, etc.).

3. Flexible Scope Control (Entire Active Tab vs. Selection Only)

Sometimes you want a holistic review of an entire document tab; other times you only want to polish a single paragraph, table, or figure you just drafted. DocuMentor AI provides a 🎯 Proofread Selection Only toggle switch in the sidebar:

OFF (Default): Proofreads the entire active tab (body text, tables, and figures/charts).
ON: Proofreads only your highlighted selection (doc.getSelection()), while still passing the full active tab's context to Gemini so that local revisions remain consistent with the overall manuscript.

4. Pedagogical Writing Coach & Learning Summary Dialog (Learning from Both AI and Other Users' Reviews)

Rather than acting as a black-box proofreader, DocuMentor AI explains why each change was suggested (💡 Reason) and provides a concise takeaway (🎓 Learning Point) in every suggestion card. Furthermore, as soon as AI proofreading finishes, it automatically displays a custom 🎓 Writing Coach & Learning Summary modal dialog that synthesizes four structured sections:

📋 Overall Manuscript Evaluation (overallFeedback): A holistic assessment of the manuscript's strengths, clarity, and cross-modal consistency across text, tables, and figures.
🛠️ What Was Revised / Pointed Out (revisionsDigest): A clear digest of the primary improvements and review points made.
🔍 Areas for Improvement & Writing Habits (weakPointsAndHabits): Recurring tendencies, grammatical habits, or structural weak points observed in the author's draft.
🌱 Actionable Advice for Future Writing (actionableTips): Simple, practical tips the author can apply in future drafts, complete with a one-click 📋 Copy to Clipboard button.

In addition to generating this summary during AI proofreading (🚀 Run Proofreading), DocuMentor AI includes a dedicated 🎓 Generate Learning Summary from Suggestions & Comments button (step2_generateLearningSummaryFromExisting). When you open a Google Document that already contains inline suggestions or comments from other users (such as colleagues, supervisors, or human editors), clicking this button analyzes those existing suggestions and comments in context and generates the Writing Coach & Learning Summary—enabling you to learn from human peer reviews just as effectively as from AI proofreading (and allowing you to re-run the summary separately at any time after proofreading).

From Black-Box Rewriting to an Active Self-Learning Loop: Architecture & 4-Stage Workflow

As illustrated in the diagram above, DocuMentor AI shifts AI proofreading away from passive external copy-paste rewrites—which overwrite the author's voice, ignore tables/charts, and offer zero explanation—toward an Active 3-Step Self-Learning Loop (1. Inspect ➔ 2. Understand ➔ 3. Internalize) powered by cross-modal alignment (Text ⇄ Tables ⇄ Charts) and a bottom-to-top UTF-16 index engine.

When the user clicks 🚀 Run Proofreading (Suggest & Coach) in the Google Docs sidebar, DocuMentor AI executes a structured 4-stage pipeline, updating its real-time Process Dashboard at each step:

STEP 1: Fetch Document & Parse Structure (step1_fetchDocument)
- Calls documents.get with includeTabsContent=true, suggestionsViewMode=SUGGESTIONS_INLINE, and commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED.
- Identifies the user's currently active tab (doc.getActiveTab()) and extracts settled text blocks, structured tables (converted to Markdown), visual figures/charts (contentUri), and any existing unresolved suggestions and active comment threads (existingComments).
- If the Proofread Selection Only toggle is enabled, maps doc.getSelection() to exact UTF-16 character ranges and target element IDs within the active tab.
STEP 2: Multimodal Analysis & Coaching via Gemini (step2_generateProofreading)
- Fetches binary image data for embedded figures/charts in parallel via UrlFetchApp.fetchAll(), uploads them to the Gemini File API (upload/v1beta/files), and passes their file URIs (fileData.fileUri) in the prompt so that even long manuscripts with many figures remain lightweight.
- Sends the full active tab context, target editable blocks/tables/figures, and optional custom prompt instructions to Gemini (gemini-3.8-flash or gemini-4-argon) using Structured Outputs (responseSchema), and immediately deletes all uploaded temporary files from the Gemini File API (DELETE v1beta/files/... inside a finally block) once the response is received.
- Enforces 100% single-language output matching the selected UI mode (English EN or Japanese JA).
STEP 3: Build Suggest & Comment Payloads (step3_buildRequestBody)
- Matches each proposed originalText against the settled text blocks to resolve exact startIndex and endIndex coordinates.
- Sorts all text replacement ranges in descending index order (from the bottom of the document to the top) so that earlier character indices never shift during batch execution.
- Constructs deleteContentRange and insertText requests scoped with the active tab's tabId under writeControl: { writeMode: "SUGGEST" }.
STEP 4: Apply Suggestions & Educational Comments (step4_applySuggestions)
- Executes the SUGGEST batch update via documents.batchUpdate, extracts createdSuggestionIds from suggestionResponses, and attaches addCommentReply requests (Reason and Learning Point) to each inline suggestion card.
- Because direct inline edit suggestions (WriteMode.SUGGEST) cannot be applied to figures, re-fetches the updated post-suggestion indices and executes insertComment requests—with an automatic 3-tier anchor range fallback (exact element range ➔ containing paragraph range ➔ nearest settled text block)—to reliably attach review comments directly to figures/charts (VISUAL_1, etc.) and overall tables (TABLE_1, etc.).
- Opens the 🎓 Writing Coach & Learning Summary custom modal dialog.

Step-by-Step Installation & Usage Guide

You can install and run DocuMentor AI in any Google Document by following these steps:

1. Create or Open a Google Document

Open Google Docs and create a new document or open an existing manuscript you wish to proofread.
In the top menu bar, click Extensions > Apps Script to open the Google Apps Script editor.

2. Copy and Paste the Script Files (`src/`)

In the Apps Script editor, set up the following three files from the src/ directory of the repository:

Enable appsscript.json (Manifest File):
- In the Apps Script editor, click Project Settings (the gear icon ⚙️ on the left sidebar) and check the box "Show 'appsscript.json' manifest file in editor".
- Return to the Editor (< > icon), select appsscript.json, and replace its contents with src/appsscript.json (this enables the Docs Advanced Service v1 and configures the required OAuth scopes so UrlFetchApp can call the latest Google Docs REST API v1 suggestion and comment endpoints directly via ScriptApp.getOAuthToken()).
Copy code.js into Code.gs:
- Select the default Code.gs file in the editor and replace its entire contents with src/code.js.
Create index.html:
- Click the + button next to Files in the left panel and select HTML.
- Name the file index (it will automatically appear as index.html—do not type .html in the name prompt).
- Paste the entire contents of src/index.html into this file.
Save the Project:
- Press Ctrl + S (or Cmd + S on macOS) or click the Save project (floppy disk 💾) icon.

3. Reload Google Docs & Launch from the Custom Menu

Close the Apps Script tab and reload (refresh) your Google Docs browser tab.
After a few seconds, a new custom menu ✦ DocuMentor AI will appear in the Google Docs menu bar.
Click ✦ DocuMentor AI > Open Dashboard.
(First-time run only) Google will prompt you to authorize the script permissions (documents, script.container.ui, script.external_request). Complete the authorization flow and click ✦ DocuMentor AI > Open Dashboard again.

4. Configure Settings & Run Proofreading (How to Use the Sidebar)

Once launched from ✦ DocuMentor AI > Open Dashboard, the DocuMentor AI sidebar appears on the right side of Google Docs, organized into intuitive control cards and a live process dashboard:

First, Register Your Gemini API Key (⚙️ AI Engine & API Settings):
- When you launch the application and the sidebar opens, first register your API key for using Gemini. Enter your Gemini API Key (obtainable from Google AI Studio) in the AI Engine & API Settings card and click Save. Once saved in PropertiesService.getUserProperties(), the card displays 🔒 API Key Configured (Saved) with a Reset link so you do not need to re-enter it in future sessions.
- Under Gemini Model, select either gemini-3.8-flash (Default / Fast) for rapid daily proofreading or gemini-4-argon (High Precision) for deep multimodal and structural analysis.
- At the top-right of the sidebar header, toggle between EN (English) and JA (Japanese) to switch both the UI language and 100% of Gemini's output language. Clicking DocuMentor AI ⓘ in the header (or DocuMentor AI in the footer) opens the About DocuMentor AI modal dialog (Developer: Kanshi Tanaike, Version: v1.0.0, and GitHub repository link).
Switch the Proofreading Scope ("Proofread Selection Only" Toggle):
- Inside the ✍️ Proofreading Scope & Controls card, turning ON the "🎯 Proofread Selection Only" toggle switch proofreads only the selected part (any specific paragraph, sentence, table cell, table, or figure you highlight in the document).
- Leaving the "🎯 Proofread Selection Only" toggle switch OFF (Default) proofreads the entire active tab (text, tables & figures).
Add Additional Instructions via Custom Prompt (Optional):
- When proofreading, it is also possible to add additional instructions as a Custom Prompt. You can type specific requests into the Additional Proofreading Instructions text box (e.g., "Refine the text, tables, and charts for a professional business report.") or click one or more of the preset prompt chips (#Concise & Logical, #Business Tone, #Tables & Charts, #Grammar & Flow).
Execute Proofreading ("Run Proofreading") & Automatic Learning Summary:
- Click the primary "🚀 Run Proofreading (Suggest & Coach)" button (or "📝 Generate Initial Text from Prompt" if the active tab is currently empty).
- As the 4-stage pipeline runs, each step in the 📊 Process Dashboard (1 Fetch Text, Tables & Figures ➔ 2 Generate AI Proofreading & Coaching ➔ 3 Build Suggestion Request Body ➔ 4 Apply Suggestions & Comments) updates in real time.
- When the pipeline finishes, the 🎓 Writing Coach & Learning Summary custom modal dialog automatically pops up with a 📋 Copy to Clipboard button, and a 📖 Re-open Latest Learning Summary Dialog button appears in the sidebar.
Generate a Learning Summary from Existing Suggestions & Comments (Learn from Other Users' Feedback too):
- Click the "🎓 Generate Learning Summary from Suggestions & Comments" button right below the Run Proofreading button to generate a Writing Coach & Learning Summary directly from existing suggestions and comments found in the Google Document when you open it (without adding or modifying any suggestions or comments in the document). This enables you to learn effectively from edits and review comments made by other users (colleagues, supervisors, or human editors).
- Note that while pressing "🚀 Run Proofreading" automatically generates the Writing Coach & Learning Summary, you can also press "🎓 Generate Learning Summary from Suggestions & Comments" separately at any time afterward to re-analyze and generate the summary from the current suggestions and comments in the document.
Accept or Delete All Suggestions & Comments with One Click:
- Clicking the "✅ Accept All Suggestions" button accepts all pending inline suggestions in the active tab at once.
- Clicking the "🧹 Clear All Suggestions" button rejects and clears all pending inline suggestions in the active tab at once.
- Clicking the "🗑️ Clear All Comments" button deletes all active comments (including figure/table review comments created via insertComment) in the active tab at once.

Testing with the Sample Manuscript (`sample/`) & Live Demonstration

To help you immediately test how DocuMentor AI works across body text, a structured table, and an embedded figure/chart, a ready-to-use sample manuscript is provided in the sample/ directory of the repository. Both screenshots below were captured using this exact sample manuscript:

sample/sample_article.md: Contains an introductory draft about Google Apps Script (GAS) and Gemini AI integration that intentionally includes redundant phrasing, colloquialisms, and grammatical awkwardness (e.g., "most biggest advantage", "boring daily routine works", "special softwares"), along with a compact 2-data-row (3 rows including the header) Markdown comparison table and a reference to sample/sample_figure.png sized to fit neatly on a single page.
sample/sample_figure.png: A composite diagram and bar chart ("Figure 1: GAS Automation Architecture & Daily Task Time Comparison") designed for multimodal visual inspection.

How to Load the `sample/` Files into Google Docs

Import or Paste the Markdown Content:
- Option A (Paste from Markdown): Copy the contents of sample/sample_article.md, right-click inside your Google Doc, and select Paste from Markdown (available in Google Docs when "Enable Markdown" is turned on under Tools > Preferences), or paste the text and create the table directly.
- Option B (Open in Google Drive): Upload sample/sample_article.md to Google Drive and open it with Google Docs.
Insert the Sample Figure:
- Place your cursor right below the table, click Insert > Image > Upload from computer, and select sample/sample_figure.png.
Test Both Proofreading Modes:
- Full Active Tab Mode (Toggle OFF): Leave 🎯 Proofread Selection Only turned OFF and click 🚀 Run Proofreading (Suggest & Coach) to see inline text edits, table cell refinements, anchored comments on TABLE_1 and VISUAL_1, and the pop-up 🎓 Writing Coach & Learning Summary dialog.
- Selection-Only Mode (Toggle ON): Click 🧹 Clear All Suggestions (and 🗑️ Clear All Comments), highlight a single paragraph, table cell, or the figure, switch 🎯 Proofread Selection Only ON, and run proofreading again to verify scoped suggestions and comments.

Before Proofreading: The `sample/` Manuscript Loaded into Google Docs

Below is the result of loading sample/sample_article.md and inserting sample/sample_figure.png into Google Docs. It introduces Google Apps Script (GAS) and Gemini AI automation, accompanied by the 2-data-row (3 rows including the header) comparison table and the composite figure (Figure 1: GAS Automation Architecture & Daily Task Time Comparison). Notice that the draft intentionally contains several common writing habits and awkward expressions—such as conversational fillers ("is basically a coding platform that is provided by"), a double superlative ("The most biggest advantage"), uncountable noun errors ("any special softwares"), and wordy phrasing:

After Running DocuMentor AI on the `sample/` Manuscript

Next, we open the DocuMentor AI sidebar from the custom menu (✦ DocuMentor AI > Open Dashboard), select gemini-4-argon (High Precision), and click 🚀 Run Proofreading (Suggest & Coach) on our loaded sample document. Within seconds, the 4-stage pipeline completes:

Looking closely at the result of proofreading the sample manuscript above, we can observe several key capabilities working together seamlessly:

Precise Inline Suggested Edits & Anchored Comments Across Paragraphs, Table Cells & Figures:
- In the first paragraph, "Google Apps Script (GAS) is basically a coding platform that is provided by Google, and it is made based on the JavaScript language." is cleanly suggested to be replaced with "Google Apps Script (GAS) is a JavaScript-based coding platform provided by Google."
- The second sentence ("The most biggest advantage of using GAS is because you can very easily connect and integrate with many various Google apps like Sheets, Docs, and Gmail that we are using every single day to automate boring daily routine works.") is refined into "The biggest advantage of using GAS is that it easily integrates with everyday Google apps—such as Sheets, Docs, and Gmail—to automate repetitive daily tasks."
- In the second paragraph, "First of all, the way to start using GAS is super simple and you totally do not need to install any special softwares on your computer at all." is tightened to "Getting started with GAS is straightforward and requires no special software installation." and "There is a merit that you can immediately start writing code just by opening your web browser." is refined to "You can immediately start writing code directly in your web browser."
- Inside the table header (TABLE_1), Task Time is suggested to be updated to Execution Time to match the vertical axis label (Execution Time (Minutes)) in Figure 1. Furthermore, notice the yellow comment highlight on Target App in TABLE_1 and the yellow highlight border directly around Figure 1 (VISUAL_1)—confirming that DocuMentor AI has also attached anchored Google Docs review comments (insertComment) directly onto both the table and the figure.
- In the final paragraph below Figure 1, the first sentence ("Also, recently it has become possible to call generative AI APIs like Gemini by using UrlFetchApp, so you are able to create your own custom AI tools for your business tasks.") is refined into "Additionally, you can now call generative AI APIs like Gemini using UrlFetchApp to build custom AI tools for your business workflows (see Table 1 and Figure 1)."—explicitly citing both Table 1 and Figure 1 in the narrative—and the concluding sentence ("Even for beginners of programming, since the learning hurdle is low, trying to use it as a first step of workflow improvement is very recommended.") is polished into "Because of its low barrier to entry, GAS is highly recommended for programming beginners as a first step toward workflow automation."
Educational Coaching Replies Attached to Every Suggestion Card:
- In the Google Docs comment stream in the center, each suggestion card automatically includes a reply from DocuMentor AI detailing the Category (e.g., [DocuMentor AI | Conciseness], [DocuMentor AI | Grammar & Conciseness]), the specific 💡 Reason for Revision (e.g., "Removes filler words ("basically") and wordy passive phrases ("that is provided by", "it is made based on") to create a crisp, professional opening sentence."), and an actionable 🎓 Learning Point (e.g., "Avoid conversational fillers like "basically" in technical writing, and convert relative clauses into concise modifiers where possible.").
Interactive Sidebar Controls & Real-Time Process Dashboard:
- On the right side, the sidebar displays all action buttons—including 🚀 Run Proofreading (Suggest & Coach), 🎓 Generate Learning Summary from Suggestions & Comments, 📝 Generate Initial Text from Prompt, ✅ Accept All Suggestions, 🧹 Clear All Suggestions, 🗑️ Clear All Comments, and 📖 Re-open Latest Learning Summary Dialog—alongside the completed Step 1 metrics (📑 Scope: Entire Active Tab (Tab 1), 1267 Target Chars, 0/60 Existing, 1 Tables, 1 Figures).

Holistic Self-Learning: The "Writing Coach & Learning Summary" Generated from the `sample/` Manuscript

Immediately upon completing the 4-stage pipeline on the sample manuscript (and also executable anytime on existing suggestions and comments via 🎓 Generate Learning Summary from Suggestions & Comments or viewable via 📖 Re-open Latest Learning Summary Dialog), DocuMentor AI pops up a custom modal dialog with a one-click 📋 Copy to Clipboard button. Below is the exact evaluation and learning summary generated when proofreading the sample/ text, table, and figure:

[🎓 Writing Coach & Learning Summary (DocuMentor AI v1.0.0)]

■ 📋 Overall Manuscript Evaluation
This introductory guide to Google Apps Script (GAS) clearly communicates the core value proposition of the platform, including its ease of setup, integration with Google Workspace, and connection to the Gemini AI API. However, the body text currently contains several grammatical errors, redundant modifiers, and overly conversational phrases (e.g., "most biggest," "many various," "softwares"). Furthermore, while Figure 1 and Table 1 present compelling time-saving metrics (reducing manual work from 120 minutes to 30 and 5 minutes), the body text never explicitly references the table or figure, nor does Table 1 include the 120-minute manual baseline shown in the chart. Aligning your text, table, and visual data while tightening your prose will significantly elevate the professionalism of this document.

■ 🛠️ What Was Revised
Revisions focused on eliminating redundant modifiers and conversational filler, correcting grammatical errors (such as double superlatives and uncountable nouns), improving sentence flow, and aligning the data terminology across the body text, Table 1, and Figure 1.

■ 🔍 Areas for Improvement & Writing Habits
The draft exhibits a habit of stacking redundant intensifiers ("most biggest," "many various," "totally do not... at all"), using uncountable nouns in the plural form ("softwares," "routine works"), and translating idiomatic structures directly into English ("There is a merit that...", "is very recommended"). Additionally, visual and tabular data are dropped into the document without being cited in the narrative or fully synchronized with one another.

■ 🌱 Actionable Advice for Future Writing
1. Avoid pairing superlatives or similar adjectives together (use "biggest" instead of "most biggest," and "various" instead of "many various"). 2. Remember that nouns like "software" and "work" (when meaning labor/tasks) are uncountable in English and do not take an "-s." 3. Always introduce and interpret your tables and figures in the body text, ensuring that baselines and labels match across all elements.

How This Summary Actively Promotes Self-Learning and Skill Growth

While the inline suggestions and comment replies in Google Docs show where individual sentences, table cells, and figures were reviewed, inspecting line-by-line edits alone can sometimes make it hard to see the bigger picture. Combining inline suggestions and anchored comments with this structured Writing Coach & Learning Summary creates a powerful pedagogical effect:

Balanced Macro-Level Diagnostic (📋 Overall Manuscript Evaluation & 🛠️ What Was Revised):
- The coach first affirms the strengths of the draft ("clearly communicates the core value proposition of the platform, including its ease of setup, integration with Google Workspace, and connection to the Gemini AI API") before categorizing the core areas for improvement. This gives the author a bird's-eye view of how eliminating redundant modifiers and conversational filler, fixing grammar, and aligning the body text, Table 1, and Figure 1 work together to elevate the entire manuscript.
Metacognitive Awareness of Personal Writing Habits (🔍 Areas for Improvement & Writing Habits):
- Instead of treating mistakes as isolated typos, DocuMentor AI surfaces systemic patterns and unconscious habits in the author's writing—such as stacking redundant intensifiers ("most biggest", "many various", "totally do not... at all"), using uncountable nouns in the plural form ("softwares", "routine works"), and translating idiomatic Japanese structures directly into English ("There is a merit that...", "is very recommended"). Becoming consciously aware of one's own recurring linguistic habits is the fastest way to stop repeating them.
Multimodal Document Design & Data Consistency Literacy (Text ⇄ Table 1 ⇄ Figure 1):
- Notice that the evaluation goes far beyond English grammar: by visually inspecting Figure 1 (reducing manual work from 120 minutes to 30 and 5 minutes), it points out both that the body text never explicitly references Table 1 or Figure 1 and that Table 1 omits the 120-minute manual baseline shown in the bar chart. Authors learn a vital rule of technical and academic communication—tables and figures must be explicitly cited in the narrative, and baselines and labels must be synchronized across prose, tables, and charts.
Actionable, Portable Takeaways for the Next Draft (🌱 Actionable Advice for Future Writing):
- By distilling the entire review into three concrete rules (1. avoiding paired superlatives or duplicate adjectives like "most biggest" and "many various", 2. remembering that nouns like "software" and "work" are uncountable and do not take an "-s", and 3. always introducing and interpreting tables and figures in the body text while ensuring baselines and labels match across all elements), the author receives a clear checklist they can immediately apply when writing their next article. With the 📋 Copy to Clipboard button, writers can easily log these summaries—whether generated from AI proofreading or from colleagues' existing suggestions and comments—into a personal learning notebook to track their growth over time.

Expected Impact & Practical Use Cases

Expected Benefits

Transforming AI Proofreading into Active Learning: Instead of passively accepting rewrites, authors see their original phrasing side-by-side with the suggested improvement, the specific reason, and a high-level summary of their writing habits.
Learning from Human Reviewers & Colleagues' Feedback: By clicking 🎓 Generate Learning Summary from Suggestions & Comments on a document reviewed by colleagues, supervisors, or editors, authors can synthesize scattered human suggestions and comments into a structured, actionable learning summary.
Accelerated Review Cycles: One-click Accept All Suggestions (acceptSuggestion), Clear All Suggestions (rejectSuggestion), and Clear All Comments (deleteComment) buttons allow you to accept or reset dozens of suggestions and comments across the active tab in a single batch call.
Respecting Existing Pending Suggestions: Because DocuMentor AI fetches the document with SUGGESTIONS_INLINE, it detects existing unresolved suggestions and proposes additional edits only on settled text blocks without colliding with pending changes.
Complete Bilingual Support (EN / JA): Switching between EN and JA in the sidebar header switches both the UI labels and 100% of Gemini's generated categories, reasons, and learning summaries.

Ideal Scenarios

Technical Documentation & Blog Posts: Ensuring terminology, tables, and architecture diagrams are clear, concise, and mutually consistent before publication.
Business Proposals & Executive Reports: Polishing tone and verifying that summary tables match embedded charts.
Language Learning & Non-Native English/Japanese Writing: Identifying personal recurring grammar or phrasing habits (such as redundant modifiers or uncountable noun mistakes) and copying the Writing Coach & Learning Summary into a personal study log.
Drafting from Scratch: Entering a topic into the Custom Prompt box on an empty tab and clicking 📝 Generate Initial Text from Prompt to create a structured starting draft, followed by iterative coaching passes.

Continuous Evolution & Feature Updates: Performance Optimization and Pedagogical Enhancements

Following the initial release (v1.0.0), DocuMentor AI is continuously evolving to streamline large-manuscript performance and deepen active-recall learning based on real-world usage and community feedback. Below is a breakdown of the architectural and pedagogical enhancements introduced across each release (v1.0.1 and v1.0.2), along with a version-by-version comparison table.

Streamlining Large-Manuscript & Selection-Scoped Proofreading via the Gemini File API

In the initial release (v1.0.0), while embedded figures and charts (VISUAL_1, etc.) were uploaded as binary files to the Gemini File API and referenced via fileData.fileUri, the manuscript's body text, Markdown tables (TABLE_1, etc.), and target editable text blocks were embedded directly inside the generateContent JSON prompt string. Moreover, when "🎯 Proofread Selection Only" was turned ON, v1.0.0 still included the entire active tab's text inside the prompt alongside the selected blocks.

To minimize JSON serialization overhead, request payload size, and token costs on long documents, v1.0.1 introduced three architectural improvements:

Uploading the Manuscript Text & Tables as a Markdown File via the Gemini File API (fileData.fileUri)
- Step 2 (step2_generateProofreading and step2_generateLearningSummaryFromExisting) packages the target manuscript data—including Target Editable Settled Text Blocks, Target Tables, Target Figure Metadata, and Review History—into a structured UTF-8 Markdown file (manuscript_context.md, mimeType: "text/markdown").
- This Markdown file is uploaded to the Gemini File API (upload/v1beta/files using the resumable upload protocol) in the exact same parallel UrlFetchApp.fetchAll() batch as any embedded figure images, referenced in contents[].parts via fileData.fileUri, and automatically deleted alongside all image files in the finally block (deleteGeminiFiles_).
True Selection-Scoped Extraction & Upload (selected_excerpt.md)
- When "🎯 Proofread Selection Only" (selectionOnly) is turned ON, Step 1 (parseDocumentStructure_) and Step 2 (buildProofreadingPromptAndSchema_) extract, package, and upload strictly the selected portion (selected_excerpt.md—containing only the highlighted text blocks, selected tables, and selected figures) with zero unselected text shipped.
Eliminating Redundant Text Duplication & Minimizing Client–Server IPC Payloads
- Redundant duplication between full-tab text and target editable text blocks was removed from the uploaded context, and Step 3 (step3_buildRequestBody) transfers only the compact target block coordinates between the sidebar UI and the Apps Script server.

Active-Recall Hint-Only Coaching Mode & Resolved Review History Extraction

As writers and reviewers tested the workflow across iterative review cycles, two important pedagogical and architectural requirements emerged—both of which were implemented in v1.0.2:

💡 Hint-Only Mode (PROOFREAD_HINT_ONLY — Comment Without Inline Rewrite)
- Motivation: Even when WriteMode.SUGGEST displays the Reason and Learning Point alongside a proposed edit, having the finished rewrite already sitting in the document makes it tempting to passively click Accept without trying to fix the sentence yourself first.
- Implementation in v1.0.2: A "💡 Hint-Only Mode (Comment Without Rewrite)" toggle switch was added to the Proofreading Scope & Controls card in the sidebar:
  - When OFF (Default): Operates in standard Suggest & Coach mode (deleteContentRange + insertText with writeControl: { writeMode: "SUGGEST" } + addCommentReply).
  - When ON: Step 3 (step3_buildRequestBody) and Step 4 (step4_applySuggestions) do not propose inline text replacements on the canvas. Instead, they anchor a native Google Docs comment (insertComment) directly onto the exact UTF-16 character range of each flagged phrase, displaying only the 🎯 Flagged Phrase (originalText), 💡 Issue (reason), and 🎓 Coaching Hint (learningPoint).
  - Collapsible Reference Rewrite in the Sidebar: Each card in Step 2 of the sidebar dashboard places the AI's reference rewrite (suggestedText) inside a collapsible <details> accordion labeled 👁️ Show Reference Rewrite (After Trying Yourself), allowing the author to revise the sentence on their own first and compare against Gemini's reference rewrite afterward.
  - Zero-Shift Phase 2 Optimization: Because insertComment does not insert or delete characters in the document body, character indices do not shift during Phase 1 of Step 4 when Hint-Only Mode is active—allowing Phase 2 (anchoring multimodal comments on VISUAL_N and TABLE_N) to execute immediately without an extra documents.get re-fetch round-trip.
📜 Resolved Review History Extraction & Inclusion (INCLUDE_RESOLVED_HISTORY)
- Motivation: In Google Docs, once an author or reviewer accepts/rejects inline suggestions or clicks Resolve on comment threads, those threads disappear from the main document canvas. Previously (v1.0.0 and v1.0.1), this prevented generating a cumulative 🎓 Writing Coach & Learning Summary after finishing a review pass, or informing the AI about edits the author had already intentionally rejected.
- Implementation in v1.0.2: Calling the Google Docs API (v1 documents.get) with commentsViewMode=COMMENTS_VIEW_MODE_INCLUDED returns both open and resolved threads in the raw JSON response. Step 1 (extractCommentAndSuggestionThreads_) now inspects docJson.comments, docJson.suggestions, documentTab.comments, and documentTab.suggestions to separate active open threads (existingComments) from resolved review history (resolvedReviews—classified as RESOLVED, ACCEPTED, REJECTED, or RESOLVED_SUGGESTION):
  - Collapsible Resolved Review History Ledger in Step 1: Whenever resolved comments or settled suggestions exist in the active tab, Step 1 displays the metric as Active / Resolved and renders an expandable 📜 View Resolved Review History ledger showing each historical thread's status badge, reviewer name, anchor quote, and comment/reply text.
  - Cumulative Learning Summary & Rejection-Aware Proofreading (📜 Include Resolved Review History Toggle): Turning ON the "📜 Include Resolved Review History" toggle switch includes all extracted resolved reviews in the Markdown context file uploaded to the Gemini File API—enabling 🎓 Generate Learning Summary from Suggestions & Comments to synthesize a complete study guide even when 0 active threads remain on the canvas, and preventing 🚀 Run Proofreading from re-suggesting previously rejected edits.

Version-by-Version Feature Comparison

Feature / Aspect	`v1.0.0` (Initial Release)	`v1.0.1`	`v1.0.2`
Manuscript Text & Tables Delivery	Embedded directly inside the `generateContent` JSON prompt string.	Uploaded as a temporary Markdown file (`text/markdown`) to the Gemini File API (`fileData.fileUri`).	Same parallel Gemini File API Markdown upload, enriched with optional Resolved Review History.
Embedded Figures (`VISUAL_N`) Delivery	Uploaded to the Gemini File API (`image/png`) and referenced via `fileData.fileUri`.	Uploaded in parallel with the manuscript Markdown file in a single `UrlFetchApp.fetchAll()` batch.	Same parallel upload + automatic `finally` cleanup.
Proofread Selection Only (`ON`)	Restricted editable blocks to the selection, but still sent full-tab text in the prompt.	Extracts and uploads strictly the selected portion (`selected_excerpt.md`)—zero unselected text shipped.	Preserves strict selection-scoped upload and supports both Suggest Mode and Hint-Only Mode.
Text Coaching Mode on Canvas	Inline replacement (`WriteMode.SUGGEST`) + `addCommentReply` only.	Inline replacement (`WriteMode.SUGGEST`) + `addCommentReply` only.	Switchable between Standard Suggest Mode (`WriteMode.SUGGEST`) and 💡 Hint-Only Mode (`insertComment` without inline rewrite + collapsible reference rewrite in sidebar).
Resolved Comments & Accepted/Rejected Suggestions	Ignored (`status === "RESOLVED"` filtered out; only pending inline suggestions inspected).	Ignored (only active suggestions and open comments extracted).	Extracted via `extractCommentAndSuggestionThreads_`, viewable in the Step 1 History Ledger, and toggleable via 📜 Include Resolved Review History.
Learning Summary after Accepting/Resolving All Reviews	Could not run once active suggestions and open comments reached `0`.	Could not run once active suggestions and open comments reached `0`.	Fully supported when 📜 Include Resolved Review History is ON—synthesizes lessons from resolved comments and accepted/rejected suggestions.

How These Updates Enhance Practical Workflows

Compact Prompts & Fast Selection Polishing (v1.0.1+): Whether your Google Doc is 2 pages or 50 pages long, uploading manuscript_context.md (or selected_excerpt.md in Selection-Only mode) in parallel with figure images keeps the generateContent prompt tiny and fast with zero extra sequential HTTP round-trips.
True Active-Recall Writing Practice (v1.0.2+ 💡 Hint-Only Mode): Writers, students, and language learners who want to avoid passive AI reliance can toggle 💡 Hint-Only Mode ON. Flagged sentences are highlighted with diagnostic coaching hints in Google Docs comments, letting the author try rewriting the sentence themselves before expanding the reference rewrite in the sidebar.
End-of-Review Retrospective Learning (v1.0.2+ 📜 Include Resolved Review History): You no longer have to remember to run the Learning Summary before resolving comments or accepting/rejecting suggestions. Even after a collaborative review cycle is completely finished and all threads are resolved, turning ON 📜 Include Resolved Review History and clicking 🎓 Generate Learning Summary from Suggestions & Comments distills the entire review history into a permanent, copyable study guide.

Summary

By combining the new Google Docs API Suggestion & Comment Management features (WriteMode.SUGGEST, addCommentReply, insertComment, acceptSuggestion, rejectSuggestion, deleteComment) with Gemini's multimodal reasoning, DocuMentor AI bridges the gap between automated proofreading and human skill development. Moreover, building DocuMentor AI with Gemini 4 Argon—and running gemini-4-argon as its high-precision proofreading and coaching engine—demonstrated the remarkable power of Gemini 4 Argon in both architecting complex Google Workspace applications and performing deep, cross-modal manuscript analysis across text, tables, and charts.

All source code and sample files are available on GitHub:

Repository: https://github.com/tanaikech/DocuMentorAI

Reflections on the Power of Gemini 4 Argon

Throughout the development and testing of DocuMentor AI, I had the opportunity to experience the capabilities of Gemini 4 Argon first-hand—both as an AI software engineer that built the application and as the multimodal reasoning engine running inside it. Here are the key points that truly amazed me about the power of Gemini 4 Argon:

1. The Initial Prompt Used to Build the Application

To develop this application, the initial prompt I gave to Gemini 4 Argon was simply the following single paragraph:

Build a Google Docs add-on using Google Apps Script, the Gemini API, and the new Google Docs API v1 suggestion and comment features (`WriteMode.SUGGEST`, `addCommentReply`, `insertComment`, `acceptSuggestion`, `rejectSuggestion`, and `deleteComment`). Instead of overwriting the document directly, the add-on should proofread the active tab (or selected range)—including body text, tables, and embedded figures—by applying inline suggested edits, attaching a short reason and learning point to each suggestion, and displaying a "Writing Coach & Learning Summary" dialog so the author can actively learn from the revisions.

2. One-Shot Feature Implementation That Ran Without a Single Error

What surprised me first was that from this single prompt alone, Gemini 4 Argon implemented all of the envisioned features—and the generated code worked right out of the box without any errors. Even though the prompt only described what the add-on should achieve at a high level, Gemini 4 Argon autonomously designed the 4-stage pipeline, the interactive sidebar with real-time progress tracking, the batch accept/clear controls, and the custom modal dialog for the Writing Coach & Learning Summary.

3. Flawless Document Index Calculation (`startIndex` / `endIndex`) from `documents.get`

Anyone who has worked with the Google Docs API (v1) knows that calculating character indices (startIndex and endIndex) for documents.batchUpdate is notoriously tricky—especially when a document contains multiple paragraphs, nested table cells, embedded images, and existing unresolved inline suggestions (SUGGESTIONS_INLINE). I was amazed that Gemini 4 Argon parsed the structural data from documents.get and constructed the request bodies for suggestions and comments using the exact character indices without a single off-by-one mistake. It even automatically implemented descending index sorting (applying replacements from the bottom of the document to the top) so that earlier character indices never shift during a batch update.

4. Autonomous Multi-Step Pipeline for Extracting Google Docs Figures (`contentUri` ➔ Binary ➔ Base64 / Gemini File API)

When passing figures embedded in a Google Document to Gemini for multimodal inspection, documents.get does not return raw image bytes—it only returns temporary URLs (contentUri) nested inside inlineObjects or positionedObjects. Without being explicitly instructed on the low-level mechanics, Gemini 4 Argon implemented the entire multi-step process from that single initial prompt: extracting each image's contentUri URL from documents.get, fetching the binary image data via UrlFetchApp.fetchAll(), converting the binary blobs into Base64 strings, and passing them as inlineData payloads to the Gemini API alongside the document text and Markdown tables. (Note: To further optimize the add-on for academic papers and long reports containing many figures, we subsequently upgraded this step to upload the fetched binary images via the Gemini File API (upload/v1beta/files), pass their fileData.fileUri references in the prompt, and automatically delete the temporary files (DELETE v1beta/files/... inside a finally block) right after content generation.)

5. Additional Technical Highlights That Showcased Gemini 4 Argon's Depth

Beyond the points above, several other engineering details stood out during development and testing:

Two-Phase Chained batchUpdate Orchestration (createdSuggestionIds ➔ addCommentReply & Post-Suggestion insertComment Anchoring): Because you cannot attach a comment reply to a suggestion before that suggestion exists in Google Docs, Gemini 4 Argon automatically split Step 4 into a chained batch workflow—first executing deleteContentRange and insertText under writeControl: { writeMode: "SUGGEST" }, extracting the newly generated createdSuggestionIds from suggestionResponses, and immediately firing a second batchUpdate with addCommentReply to link the educational Reason and Learning Point to each exact inline edit, followed by re-fetching updated post-suggestion indices to anchor insertComment review comments onto figures (VISUAL_1) and tables (TABLE_1).
Bridging DocumentApp Selection and the Docs REST API (v1): The Google Docs REST API (v1) operates on global UTF-16 character indices and has no awareness of the user's live cursor highlight, whereas Apps Script's DocumentApp.getActiveDocument().getSelection() returns RangeElement objects without REST API indices. Gemini 4 Argon seamlessly bridged these two APIs to make the "Proofread Selection Only" toggle and multi-tab (tabId) scoping work reliably.
Cross-Modal Data Verification at Runtime: When running gemini-4-argon inside the add-on on the sample/ manuscript, it went far beyond grammar correction—visually reading the bar chart in Figure 1 (120 min for Manual Work vs. 5 min for GAS + Gemini AI), noticing that the 120-minute baseline was missing from Table 1 and the body text, and proposing coordinated edits and learning advice across text, table, and chart.

AlphaEvolve and Gemini: Autonomous Algorithm Discovery for Unified Disaster Prediction

Tanaike — Wed, 14 Oct 2026 02:48:03 +0000

📄 Published Paper (Open Access on Zenodo):

Autonomous Discovery of Unified Multi-Hazard Prediction Theory from Netatmo IoT Weather Big Data Using AlphaEvolve

🔗 Full Paper URL: https://zenodo.org/records/23354598

💻 Sample Scripts Repository (GitHub): https://github.com/tanaikech/alphaevolve-multi-hazard

"The book of nature is written in the language of mathematics." — Galileo Galilei

Today, that mathematical language can be autonomously written as an algorithm, assembled into a predictive model, and elevated into a physical theory by artificial intelligence.

1. The Invisible Whisper Before the Catastrophe — And a New Way to Do Science

Imagine sitting in a quiet office in downtown Tokyo or suburban Osaka on a hot, muggy summer afternoon. Outside, the sky appears calm. Within thirty minutes, however, the atmosphere darkens into pitch-black fury. A violent "guerrilla rainstorm"—an extreme localized convective cloudburst—dumps 80 millimeters of torrential rain in under an hour. Underground subway entrances are inundated, calm residential roads turn into raging rivers, and vehicles are trapped beneath flooded railway underpasses.

Or imagine an inland geological fault kilometers beneath our feet, quietly accumulating mechanical shear stress over decades. Without warning, the fault ruptures in an instant, generating devastating seismic shaking that levels homes before anyone can take cover.

Natural disasters—extreme convective downpours, deadly inland earthquakes, and explosive volcanic eruptions—are among the most formidable threats confronting human civilization. Every year, they claim thousands of lives and inflict hundreds of billions of dollars in economic devastation. Providing accurate, early warning for these events is one of the highest callings of modern applied science. Yet, it has long remained one of the most stubborn, mathematically vexing frontiers in geophysics.

Why Is Predicting Natural Disasters So Excitingly, Terrifyingly Difficult?

For decades, the standard approach in atmospheric and Earth sciences has relied upon sparse, high-cost governmental observation networks. In Japan, for example, the official meteorological radar network and the automated surface station network (AMeDAS) operate with an average spacing of roughly 17 kilometers.

While 17 kilometers is well-suited for broad weather forecasting (such as tracking a 1,000-kilometer typhoon moving across the Pacific), it leaves vast spatial blind spots for micro-scale phenomena:

Micro-Scale Spatiotemporal Scale: A localized convective rainstorm cell forms over a horizontal diameter of only 2 to 3 kilometers and transitions from an innocent cumulus cloud to a violent downburst within 15 to 20 minutes. It can easily mature and dump destructive rain entirely within the blank space between two official observation towers.
Non-Linear Geophysical Chaos: Atmospheric motions are governed by the Navier-Stokes equations, where microscopic thermal eddies cascade unpredictably into macroscopic storms.
Severe Environmental Noise: Separating an actual precursor from background atmospheric noise is an operational nightmare. A sudden drop in air pressure could signify an oncoming cold front, a mundane passing shower, or the shockwave of a distant volcanic explosion. A false alarm rate as low as 5% is unacceptable in civil defense—frequent false alarms breed disaster fatigue, causing citizens to ignore warnings when a real catastrophe strikes.

The Core Message of This Article: Autonomous Algorithm Creation for Model and Theory Building

For years, I asked myself a question that kept me awake at night:

What if the signals of nature’s impending fury are not absent, but simply hidden in plain sight—whispering across thousands of micro-sensors mounted on citizen balconies? And what if, instead of humans manually guessing thresholds, an AI could autonomously write the mathematical algorithms needed to build a predictive model and establish a unified physical theory?

In traditional science and engineering, building a disaster prediction theory requires a painstaking manual chain:

A human scientist manually writes algorithms (conditional rules, filters, and scoring formulas) based on intuition.
Those algorithms are combined to construct a predictive model.
By testing the model against reality, the scientist attempts to formulate a physical theory of disaster prediction.

When humans do this by hand across multiple hazards, cognitive bias and mathematical complexity get in the way. Conversely, if you use a standard Deep Neural Network (DNN), the AI builds a "black-box" model of millions of inscrutable weights—meaning it cannot give you a transparent algorithm, nor can it build a human-readable physical theory.

In my latest research paper, "Autonomous Discovery of Unified Multi-Hazard Prediction Theory from Netatmo IoT Weather Big Data Using AlphaEvolve" [10], now published on Zenodo (https://zenodo.org/records/23354598) alongside our open-source sample scripts on GitHub (https://github.com/tanaikech/alphaevolve-multi-hazard), I demonstrated a third path using Google DeepMind’s AlphaEvolve and Gemini 3.8 Flash:

Step 1 (Autonomous Algorithm Creation): AlphaEvolve autonomously writes, mutates, and refines explicit Python mathematical algorithms without human threshold tuning.
Step 2 (Predictive Model Construction): Those autonomously generated algorithms directly construct a high-speed, deterministic multi-hazard prediction model that achieves 100% detection across 21 historical disasters with 0.0% false alarms.
Step 3 (Physical Theory Formulation): Because the AI-created algorithm is 100% transparent white-box mathematics, we can directly read its code and elevate it into a unified geophysical theory governing torrential rainstorms, inland earthquakes, and volcanic eruptions.

In this article, I will walk you through the physics of citizen weather data, how AlphaEvolve works, how to use AlphaEvolve in practice, how we fed 175,363 real disaster observations into AlphaEvolve, and the physical laws the AI discovered on its own.

2. The Secret Life of Weather Data: Why the Atmosphere Senses the Earth’s Fury

To ordinary citizens, a personal weather station mounted on an apartment balcony is just a gadget that tells them if they need an umbrella. To a geophysicist, however, it is an ultra-sensitive, high-frequency stethoscope pressed against the living skin of planet Earth.

Over the past decade, crowdsourced Internet of Things (IoT) weather networks—most notably the global Netatmo Personal Weather Station (PWS) ecosystem [3]—have quietly revolutionized observational geography. Unlike sparse governmental towers, hundreds of thousands of citizen-owned Netatmo stations blanket dense urban centers. In metropolitan Tokyo and Kansai, the average distance between stations shrinks from 17 kilometers down to just 1 to 2 kilometers, continuously logging barometric pressure, ambient temperature, relative humidity, and wind gusts every few minutes.

Figure 1 | How Balcony Weather IoT Decodes Natural Disasters. The Micro-Atmospheric Stethoscope: Resolving extreme hazards invisible to sparse governmental radars across three physical domains.

Walking Through Figure 1: Three Hazards Captured on Balconies

As illustrated in Figure 1, crowdsourced IoT weather networks can capture physical precursors across three wildly different geophysical domains because the Earth's lithosphere, surface, and atmosphere are fundamentally coupled:

Guerrilla Downpours (Figure 1, Left Panel): Before a single raindrop hits the ground, the pre-storm atmosphere undergoes intense thermodynamic destabilization. High-moisture air converges, latent heat is exchanged, and moist static energy—measured by equivalent potential temperature (often designated as theta_e, which represents the total heat content of an air parcel combining sensible heat and latent heat stored in water vapor)—collapses. As cold, dense air descends in an evaporatively driven downdraft ("cold pool"), equivalent potential temperature plunges at rates exceeding 5.0 Kelvin per hour. Simultaneously, a micro-barometric surge sweeps across surface sensors several tens of minutes before radar reflects heavy precipitation aloft.
Inland Earthquakes (Figure 1, Center Panel): Under the well-established framework of Lithosphere-Atmosphere-Ionosphere Coupling (LAIC) [4], mechanical tectonic stress accumulating along seismogenic fault planes causes micro-cracking and releases subterranean radon gas. This alpha-particle ionization condenses atmospheric water vapor, releasing surface latent heat flux and driving a localized spatial thermal anomaly (delta theta_e of 30 Kelvin or greater) hours to days before the fault ruptures. Crucially, as highlighted in the purple badge in Figure 1, this tectonic heating occurs under hydrostatic, isobaric equilibrium—meaning the ambient air pressure is completely calm (pressure rate of change within 2.0 hectopascals per hour), without passing cyclonic storms.
Volcanic Eruptions (Figure 1, Right Panel): When an explosive volcanic eruption occurs, the violent blast launches an infrasonic shockwave into the lower troposphere known as an acoustic Lamb wave [2]. Propagating horizontally at the local speed of sound (approximately 310 meters per second), this pressure pulse ripples across thousands of balcony barometers. By calculating multi-channel semblance coherence across the sensor mesh, random wind noise cancels out, and true volcanic wavefronts stand out with semblance values exceeding 0.80, allowing exact real-time tracking of the blast wave.

The data was there. The physics was there. But writing the exact mathematical algorithms to combine all of this into a unified predictive model—and a unified theory—without false alarms was where human craftsmanship hit a wall.

3. My Long Journey of Crafting Disaster Models by Hand

Before turning to autonomous AI, I spent years tackling these hazards through manual theoretical physics and empirical derivation across four separate papers [6, 7, 8, 9].

Figure 2 | Research Objective, Historical Context, and Autonomous Inquiry Framework. Tracing the evolution from my four isolated manual frameworks (left) to closed-loop AI algorithm creation with AlphaEvolve and Gemini 3.8 Flash (center), culminating in a unified predictive model and physical laws (right).

Understanding the Bottlenecks in Figure 2

Figure 2 visualizes why manual model building struggled and why autonomous algorithm generation was needed:

The Left Panel (Manual Physics Frameworks in Isolated Silos): In my earlier work, I manually crafted algorithms for four separate frameworks:
1. The Urban Heat Convection (UHC) Framework [6]: Using Bolton's thermodynamic formulation [1], I derived a scalar criterion combining the time rate of equivalent potential temperature change with a local pressure anomaly ratio to detect downbursts. However, its rigid step-function thresholds suffered from blind spots during highly humid, maritime frontal boundaries.
2. The Localized Fluid Dynamics Framework [9]: A 3D helicity flux formulation and diagnostic Navier-Stokes solver nesting a 10-meter fluidic voxel inside a 1.0-kilometer grid. While precise, it operated as an isolated computational silo unable to interface with lithospheric or acoustic signals.
3. The LAIC Earthquake Precursor Framework [7]: Formulated the thermodynamic coupling between pre-seismic radon emission, surface latent heat flux, and equivalent potential temperature anomalies. While it captured precursor thermal spikes before major Japanese earthquakes, it relied on a hand-tuned scalar threshold vulnerable to passing winter bomb cyclones, producing an operational false alarm rate of roughly 6.8%.
4. Volcanic Infrasonic Lamb Wave Moveout Analysis [8]: Tracked volcanic shockwaves using moveout regression, but atmospheric wind shear introduced scattering, leaving an azimuth uncertainty of 1.78 degrees.
The Center Panel (AI Ingestion & Closed-Loop Algorithm Evolution): As depicted in the center of Figure 2, breaking down these intellectual silos required handing over the task of algorithm creation to an evolutionary AI system. By feeding 21 verified Japanese disasters and 175,363 authenticated Netatmo IoT records into Google DeepMind's AlphaEvolve and Gemini 3.8 Flash, the AI autonomously explored algorithmic structures under strict falsification penalties.
The Right Panel (Autonomous Model & Theory Deliverables): The AI autonomously writes the Python algorithm, which forms the unified multi-hazard predictive model, from which three continuous physical laws are formulated and verified on raw empirical data.

Why Human Hand-Tuning Fails When Hazards Collide

When you try to manually write algorithms to combine four separate physical models on live atmospheric data, chaos ensues:

A passing winter bomb cyclone triggers an earthquake warning because of sudden pressure swings.
A sudden squall line distorts an acoustic volcanic wave calculation.
High ambient humidity causes a rigid rain threshold to miss an impending downburst.

The human mind, constrained by cognitive biases and habit, tends to write simple linear thresholds (if x > 5.0). We struggle to invent the higher-dimensional, non-linear mathematical functions that cleanly separate all three hazards simultaneously. I needed an AI system that could autonomously create the algorithms to build the model for me.

4. Enter AlphaEvolve: An AI That Autonomously Writes Algorithms to Build Models and Theories

In 2024, Google DeepMind published FunSearch [5], demonstrating that large language models paired with evolutionary program search could discover new mathematical theorems and combinatorial algorithms beyond the reach of human mathematicians.

Building upon this philosophy, Google DeepMind introduced AlphaEvolve—an evolutionary coding agent powered by Gemini that autonomously writes, mutates, tests, and refines complex algorithmic codebases.

Figure 3 | AlphaEvolve Architecture, Mechanism, and Application Domains. Left: The 4-station cyclic engine: Seed population, Gemini 3.8 Flash AST mutator, 3-tier defensive evaluation gauntlet, and Pareto archive. Right: Core scientific use cases, quantitative benchmark comparison against deep neural networks, and anti-reward hacking forensics.

Why Autonomous Symbolic Algorithm Creation Beats Black-Box Neural Networks (Figure 3)

A common question from developers is: Why use AlphaEvolve to write Python algorithms when you could just train a Deep Neural Network (such as an LSTM or Transformer) on the sensor data?

As shown in the benchmark comparison on the right side of Figure 3, the distinction is fundamental to scientific theory building:

Neural Networks Build Black-Box Weights, Not Theories: A deep neural network adjusts millions of floating-point weights inside hidden layers. Even if it predicts a storm, you cannot read its weights to formulate a physical law of nature, nor can civil defense authorities trust an opaque black box that might hallucinate in unseen extreme weather.
AlphaEvolve Autonomously Writes Explicit Mathematical Algorithms: Instead of training opaque weights, AlphaEvolve uses Gemini 3.8 Flash to write human-readable Python equations. The output of AlphaEvolve is a clean, symbolic mathematical algorithm (evolved_hazard_dispatcher.py).
From Algorithm to Model to Theory: Because the algorithm is explicit math, it immediately serves as a fast, deterministic predictive model (running in under 1.5 milliseconds on a standard CPU) AND allows scientists to directly read the discovered equations to establish a physical theory!

Figure 4 | Inside the AI Discovery Engine: From Raw Code to Universal Equations. Tracing how AlphaEvolve replaces fragile human heuristics (Column 1) via Gemini 3.8 Flash AST refactoring and the -5,000 point Popperian falsification crucible (Column 2) to autonomously synthesize the multi-hazard predictive model and physical laws (Column 3).

Walking Through Figure 4: How Gemini Evolves the Algorithm

Figure 4 illustrates the internal mechanics of how AlphaEvolve autonomously constructs the disaster prediction algorithm:

Column 1 (Human Heuristics & Bottlenecks): Starts with a rough, human-written seed program using rigid step-function thresholds (if dtheta < -5.0), which suffers from missed storms in humid air and a 6.8% false alarm rate during winter cyclones.
Column 2 (Gemini 3.8 Flash & Popperian Gauntlet): Rather than flipping random bits like classical genetic algorithms, Gemini 3.8 Flash parses and rewrites the Python Abstract Syntax Tree (AST)—replacing crude ast.If cliffs with smooth ast.Call continuous logistic manifolds and multi-variable orthogonality gates. Every candidate program is tested against 175,363 real observations, where a single false alarm triggers a merciless -5,000 point Popperian penalty. Across 68 generations, fitness climbs from 212.40 to 399.85.
Column 3 (Autonomously Synthesized Physics Laws): The surviving champion algorithm automatically forms our unified multi-hazard prediction model and reveals three new physical principles.

5. How to Use AlphaEvolve: A Practical Guide to Autonomous Algorithm Creation

How do you actually set up and run AlphaEvolve so that it autonomously creates algorithms to build a scientific model? Even if you have never used evolutionary code search before, the workflow boils down to three clean architectural steps.

Figure 5 | How to Use AlphaEvolve: Autonomous Algorithm Creation Workflow. Column 1: Defining the Python seed skeleton with # EVOLVE-BLOCK markers. Column 2: Running the closed-loop cycle between the deterministic evaluator harness and the Gemini 3.8 Flash semantic mutator. Column 3: The 3-level autonomous elevation from AI-generated algorithm to predictive model to unified physical theory.

Step-by-Step Walkthrough of Figure 5

As illustrated in Figure 5, using AlphaEvolve requires setting up two files—a Seed Skeleton and an Evaluator Harness—and then letting the Gemini Closed-Loop Engine do the heavy lifting:

Step 1: Define the Seed Skeleton with `# EVOLVE-BLOCK` Markers (Figure 5, Column 1)

To use AlphaEvolve, you do not ask the LLM to write an entire software application from scratch. Instead, you write a standard Python skeleton where the outer infrastructure (imports, data types, and function signatures) is locked, and the core mathematical algorithm you want the AI to discover is enclosed inside # EVOLVE-BLOCK START and # EVOLVE-BLOCK END comments:

import numpy as np  # Locked outside the evolve block

# >>>>>>>>>>>>>>>>>>>>>>>> # EVOLVE-BLOCK START <<<<<<<<<<<<<<<<<<<<<<<<<<<<

def compute_rain_convective_score(theta_e_k: float, dtheta_e_dt_k_h: float,
                                 pressure_drop_10min_hpa: float, gust_ratio: float) -> float:
    """AlphaEvolve will autonomously rewrite the math inside this function!"""
    z = (-0.15 * dtheta_e_dt_k_h) + (1.2 * pressure_drop_10min_hpa) + (0.8 * (gust_ratio - 1.0))
    if theta_e_k > 340.0:
        z += 1.5
    return float(1.0 / (1.0 + np.exp(-np.clip(z, -10.0, 10.0))))

def evaluate_laic_and_gate(delta_theta_e_k: float, lpar: float,
                          dp_dt_abs_hpa_h: float, regional_std_k: float) -> bool:
    """AlphaEvolve will autonomously discover how to reject storm false alarms!"""
    return bool(delta_theta_e_k >= 8.0 and lpar >= 2.5)

# ... (additional hazard functions and dispatcher) ...

# >>>>>>>>>>>>>>>>>>>>>>>>> # EVOLVE-BLOCK END <<<<<<<<<<<<<<<<<<<<<<<<<<<<<

As highlighted in the bottom card of Figure 5 (Column 1), the developer's only job in Step 1 is to specify the input arguments (the physical observables) and the output return format. You do not need to know the optimal mathematical formula or threshold weights—AlphaEvolve will invent those autonomously.

Step 2: Connect the Evaluator Harness & Gemini Closed Loop (Figure 5, Column 2)

Next, you write an evaluator class (evaluator.evaluate(code_str)) that takes a candidate Python string generated by Gemini, executes it against your dataset, and returns two things:

A Scalar Fitness Score: A single number measuring how well the candidate model performed (rewarding true detections and early lead time, while heavily penalizing false alarms).
Diagnostic Failure Insights: Structured text feedback explaining where and why the candidate failed—for example, [{"label": "FALSE_POSITIVE_EQ", "text": "Triggered false earthquake alert during winter storm baseline"}].

Look at the cycle diagram in the center of Figure 5 (Column 2). Unlike traditional genetic algorithms that mutate code blindly at random, AlphaEvolve feeds both the parent's EVOLVE-BLOCK code and these diagnostic failure insights into Gemini 3.8 Flash via the Google GenAI SDK (google-genai). Gemini reads the diagnostics, reasons like a physicist about why the equation failed, and rewrites the Python AST to fix the flaw in the next generation!

To launch the entire evolutionary campaign from your terminal, you simply set your Gemini API key and run the campaign script:

export GEMINI_API_KEY="your_api_key_here"
python3 scripts/04_run_alpha_evolve_campaign.py --model gemini-3.8-flash --generations 100

Step 3: The 3-Level Autonomous Elevation — Algorithm to Model to Theory (Figure 5, Column 3)

Column 3 of Figure 5 illustrates why this paradigm is so transformative for science. As AlphaEvolve iterates through generations, it autonomously completes a three-level hierarchy:

Level 1 (Autonomous Algorithm): At Generation 68, AlphaEvolve outputs the champion Python algorithm (evolved_hazard_dispatcher.py), having autonomously invented non-linear activation kernels and orthogonal stability gates.
Level 2 (Predictive Model): That exported Python algorithm immediately functions as our unified multi-hazard predictive model, capable of processing live sensor streams in under 1.5 milliseconds with 100% recall and 0.0% false alarms.
Level 3 (Unified Physical Theory): Because the predictive model is written in clean, symbolic Python math rather than hidden neural weights, we can directly read the AI's code and formalize three universal laws of geophysics!

6. How We Fed 175,363 Real Disaster Observations into AlphaEvolve

A critical question for any developer or data scientist is: How do you take messy, real-world IoT sensor logs from 21 historical disasters and format them so AlphaEvolve can test thousands of algorithms in milliseconds without the AI cheating?

If you ask an evolutionary AI to read raw CSV files or compute Fast Fourier Transforms (FFTs) from scratch on 175,363 rows during every single generation, each evaluation would take several minutes—and worse, a clever AI might try to "reward hack" by peeking at file timestamps or overwriting the data arrays in memory.

To solve this, I engineered a five-script empirical pipeline (publicly available in our sample repository at https://github.com/tanaikech/alphaevolve-multi-hazard) that prepares, authenticates, pre-computes, and locks the experimental data before handing it to AlphaEvolve.

Figure 6 | How Experimental Disaster Big Data Is Fed Into AlphaEvolve. The 5-Script Empirical Pipeline: Transforming 175,363 raw Netatmo IoT observations into hardware-authenticated, read-only NumPy feature tensors (flags.writeable = False) for sub-millisecond evaluation across the 3-Tier Defensive Evaluator Harness.

Walking Through Figure 6: The 5-Script Data-to-Discovery Pipeline

Figure 6 maps out the exact software engineering pipeline used in our study to bridge raw citizen weather data with AlphaEvolve:

Stage 1: Raw Data Extraction & Hardware Authentication (`01_fetch_multi_hazard_data.py` — Figure 6, Column 1 Top)

First, 01_fetch_multi_hazard_data.py extracts 175,363 crowdsourced Netatmo observations across 23 distinct empirical catalogs:

15 Extreme Convective Rainstorms (such as the 2017 Nerima and Fuchu guerrilla downpours and Setagaya cloudbursts),
4 Major Inland Earthquakes (2016 Kumamoto M7.0, 2018 Osaka M5.6, 2018 Hokkaido Iburi M6.6, and 2021 Fukushima M7.1 — totaling 71,107 records),
2 Explosive Volcanic Eruptions (2018 Kusatsu-Shirane phreatic blast and 2018 Shinmoedake magmatic eruption),
2 Non-Disaster Control Baselines (calm summer heatwave days and violent winter bomb cyclones).

To guarantee 100% authentic empirical data (Zero Dummy Data Policy), this script verifies that every station's hardware MAC address begins with the official Netatmo IEEE OUI prefix (70:ee:50), filters out indoor sensor anomalies, and seals every CSV catalog with a cryptographic SHA-256 hash inside data_manifest.json.

Stage 2: Immutable Physics Core & Read-Only Tensor Pre-Caching (`02_immutable_physics_core.py` — Figure 6, Column 1 Middle & Bottom)

Next, 02_immutable_physics_core.py transforms the raw meteorological readings (temperature in Celsius, relative humidity in percent, sea-level pressure in hectopascals, and wind speed in meters per second) into standardized first-principles physical feature matrices for each hazard category:

For Rainstorms ([N x 4] matrix): Computes exact Bolton (1980) equivalent potential temperature (theta_e), its hourly time derivative (dtheta_e/dt), 10-minute barometric surge (dp_10min), and peak wind gust ratio (gust_ratio).
For Earthquakes ([N x 4] matrix): Computes the two-stage spatial thermal residual (delta_theta_e) relative to surrounding reference stations, the Local Precursor Anomaly Ratio (LPAR), the absolute hourly pressure change rate (|dP/dt|), and regional spatial standard deviation (regional_std).
For Volcanoes (acoustic dictionary): Applies a zero-phase Butterworth bandpass filter (0.0005 to 0.02 Hz) to isolate infrasonic pressure perturbations, performs Time-Difference-of-Arrival (TDOA) moveout regression to extract apparent sound speed (c_app), and computes normalized multi-channel array semblance (semblance).

The Crucial Engineering Trick (Figure 6, Column 1 Bottom Badge):

Once 02_immutable_physics_core.py computes these NumPy feature tensors, it locks their memory buffers as strictly read-only before caching them to disk (temp/processed_cache/*.pkl):

# Lock NumPy tensor memory buffer so evolved AI code can NEVER modify empirical data
feature_matrix.flags.writeable = False

This single architectural decision accomplishes two vital goals:

1,000x Speedup: Because heavy trigonometric, logarithmic, and FFT signal processing is pre-cached once in Stage 2, AlphaEvolve can stream all 175,363 records through a candidate algorithm in under 1.5 milliseconds in RAM!
Bulletproof Data Integrity: Even if a mutated candidate tries to cheat by modifying input arrays in place, NumPy immediately raises a ValueError: assignment destination is read-only.

Stage 3: The 3-Tier Defensive Evaluator Harness (`03_alpha_evolve_dispatcher_evaluator.py` — Figure 6, Column 2)

As shown in Column 2 of Figure 6, 03_alpha_evolve_dispatcher_evaluator.py loads the 23 read-only feature tensors into memory and tests every AI-generated candidate across three strict defensive tiers:

Tier 1 (AST Security & Anti-Cheat Scan): Uses ast.NodeVisitor to inspect the candidate's syntax tree before execution. If the code imports random, os, sys, eval, or contains hardcoded strings of historical disaster dates (like "2018-01-23"), it is instantly disqualified with a score of minus one trillion.
Tier 2 (Physics Contract & Double-Run Determinism): Executes the candidate's four functions twice on identical input vectors. If the outputs differ by more than 10 to the minus 12th power (proving hidden state or randomness) or fall outside physical probability bounds between 0.0 and 1.0, it is rejected with a score of minus one million.
Tier 3 (Multi-Hazard Empirical Benchmark & Popperian Penalty): Streams all 23 cached disaster and control tensors through the candidate algorithm. It sums the True Positive Rates (TPR) and warning lead-time bonuses across the 21 disasters, but subtracts 5,000 points for every single false alarm triggered during the 2 control baseline catalogs. Whenever a disaster is missed or a false alarm occurs, Tier 3 appends a diagnostic JSON insight to guide Gemini's next mutation.

Stage 4 & Stage 5: Campaign Execution & Standalone Verification (`04` & `05` — Figure 6, Column 3)

Finally, as shown in Column 3 of Figure 6:

04_run_alpha_evolve_campaign.py runs the evolutionary loop, feeding parent code and Tier 3 diagnostic insights into Gemini 3.8 Flash to evolve the four core functions (compute_rain_convective_score, evaluate_laic_and_gate, compute_volcanic_semblance_threshold, and dispatch_hazard_decision), exporting the winning algorithm to scripts/evolved_hazard_dispatcher.py.
05_predict_multi_hazard.py imports that exported champion algorithm and runs an independent, end-to-end verification pass across all 175,363 records, generating the cryptographic reproducibility certificate.

Figure 7 | The 4-Stage Experimental Methodology and Closed-Loop Research Pipeline. Visualizing the complete scientific workflow from IEEE OUI hardware-authenticated data ingestion (Stage 1), multi-generation AST optimization (Stage 2), continuum theory elevation (Stage 3), to independent deterministic verification (Stage 4).

Connecting the Software Pipeline to the Scientific Methodology (Figure 7)

Figure 7 summarizes how our five-script software pipeline maps directly onto the four macro-stages of autonomous scientific discovery:

Stage 1 (Top-Left): Hardware-authenticated ingestion of 175,363 Netatmo observations (Scripts 01 & 02).
Stage 2 (Top-Right): Multi-generation AST evolution under the -5,000 point Popperian falsification gauntlet (Scripts 03 & 04).
Stage 3 (Bottom-Left): Deductive theory elevation—translating the autonomously created Python algorithm into continuum differential equations.
Stage 4 (Bottom-Right): Independent zero-false-alarm empirical verification (Script 05).

7. From Autonomously Created Algorithm to Predictive Model and Unified Theory

At Generation 68, the champion Python algorithm autonomously created by AlphaEvolve and Gemini 3.8 Flash emerged not as bloated spaghetti code, but as twelve lines of transparent mathematical harmony:

# =========================================================================
# CHAMPION PYTHON ALGORITHM AUTONOMOUSLY CREATED BY ALPHAEVOLVE (GEN 68)
#
# Input telemetry schema (from pre-cached read-only feature tensors):
#   dtheta_e_dt    : Equivalent potential temp time derivative [K/h]
#   dp_10min       : 10-minute micro-barometric surge [hPa/10min]
#   gust_ratio     : Peak gust ratio u_gust / u_mean [-]
#   theta_e        : Ambient surface equivalent potential temp [K]
#   dp_dt_hpa_h    : Hourly barometric pressure derivative [hPa/h]
#   delta_theta_e  : Thermal anomaly relative to background [K]
#   c_app          : Apparent wave propagation speed [m/s]
#   semblance      : Normalized multi-channel coherence semblance [-]
# =========================================================================

# 1. Continuous Logistic Torrential Rain Kernel
z = (0.35 * max(0.0, -dtheta_e_dt) +
     1.50 * max(0.0, dp_10min) +
     1.20 * max(0.0, gust_ratio - 1.0) - 1.5 +
     1.50 * (1.0 if theta_e >= 350.0 else 0.0))
rain_score = 1.0 / (1.0 + np.exp(-np.clip(z, -10.0, 10.0)))

# 2. Dynamic Isobaric Pre-Seismic (Earthquake) Gate
isobaric_stable = abs(dp_dt_hpa_h) <= 2.0
thermal_floor   = theta_e >= 332.0
eq_gate_open    = isobaric_stable and thermal_floor
eq_score        = min(1.0, delta_theta_e / 50.0)

# 3. Multi-Hazard Kinematic Priority Dispatcher
if 300.0 <= c_app <= 330.0 and semblance >= 0.80:
    return {'alert': 'VOLCANO_LAMB_WAVE', 'conf': semblance}
elif rain_score >= 0.70:
    return {'alert': 'CONVECTIVE_TORRENTIAL_RAIN', 'conf': rain_score}
elif eq_gate_open and delta_theta_e >= 30.0:
    return {'alert': 'EARTHQUAKE_LAIC_PRECURSOR', 'conf': eq_score}
return {'alert': 'NORMAL_ATMOSPHERE', 'conf': 0.0}

Figure 8 | Discovered Symbolic Algorithm and Elevated Unified Geophysical Theory. Part A (Left): The champion Python algorithm autonomously synthesized by AlphaEvolve. Theory Elevation Bridge (Center): Deductive mathematical translation of the AI's predictive model into continuum field equations. Part B (Right): The three formulated universal physical laws: Continuous Enthalpy Potential Theory, Kinematic-Barometric Orthogonality, and Emergent Dynamic Semblance Inversion.

How the AI's Algorithm Built the Model and Revealed Three Physical Laws (Figure 8)

Look closely at the three-part progression in Figure 8. Because AlphaEvolve autonomously wrote explicit symbolic Python rules (Figure 8, Part A) to construct our multi-hazard predictive model, we can pass those rules across the Theory Elevation Bridge (Figure 8, Center) to formulate a unified geophysical theory consisting of four continuum principles (Figure 8, Part B):

Principle 1: Continuous Enthalpy Potential Theory (Rainstorms)

In my earlier manual work, I used rigid step-function thresholds that failed when humid maritime air masses triggered downpours without a sharp initial temperature cliff. AlphaEvolve autonomously discarded step functions and constructed a continuous logistic manifold. The probability of convective initiation is modeled by a smooth logistic sigmoid function taking the weighted sum of three physical terms:

Equivalent potential temperature flux convergence (weighted by 0.35, capturing downdraft evaporative cooling),
Micro-barometric surge rate (weighted by 1.50, capturing cold-pool pressure domes),
Excess wind gust ratio (weighted by 1.20, capturing surface shear turbulence), minus a dynamic potential energy barrier.

Crucially, the AI discovered on its own that this potential energy barrier should equal 1.5 under normal conditions, but drop by 1.5 down to zero whenever ambient equivalent potential temperature reaches or exceeds 350.0 Kelvin. Physically, when the urban boundary layer is already saturated with extreme moist static energy (350 Kelvin or higher), the activation energy required to trigger convective collapse vanishes! This allowed the model to sense impending downbursts during the pre-condensation phase, long before raindrops form aloft.

Principle 2: Kinematic-Barometric Orthogonality (Earthquakes)

To eliminate the 6.8% storm false-alarm rate that plagued my earlier earthquake precursor model [7], AlphaEvolve autonomously discovered a Kinematic-Barometric Orthogonality Gate. Before a spatial thermal anomaly (delta theta_e of 30 Kelvin or greater) is allowed to trigger an earthquake alert, the algorithm enforces two simultaneous physical gates:

Isobaric Calm (abs(dp_dt_hpa_h) <= 2.0): The hourly barometric pressure change must remain within 2.0 hectopascals per hour. Because genuine pre-seismic LAIC heating originates from tectonic stress and radon ionization deep underground, it manifests under calm hydrostatic equilibrium. Passing synoptic storms and winter bomb cyclones always involve strong baroclinic pressure drops (exceeding 2.0 hectopascals per hour) and are therefore mathematically annihilated!
Thermodynamic Floor (theta_e >= 332.0): The ambient equivalent potential temperature must be at least 332.0 Kelvin, ensuring sufficient atmospheric water vapor is present to release latent heat via radon ion-induced nucleation, eliminating cold-weather sensor noise.

Principle 3: Emergent Dynamic Semblance Inversion (Volcanoes)

For explosive volcanic eruptions, the AI synthesized a joint acoustic filter requiring apparent horizontal propagation speeds between 300.0 and 330.0 meters per second alongside multi-channel array semblance coherence of at least 0.80. Because tropospheric Lamb waves propagate at the speed of sound (approximately 310 meters per second), true volcanic shockwaves interfere constructively across hundreds of balcony barometers, while local wind gusts cancel out asymptotically.

Principle 4: The Kinematic Wave-Speed Priority Dispatcher

Finally, how did the AI's algorithm prevent alert collisions when multiple signals occur at once? Look at lines 191 to 197 of the discovered code: AlphaEvolve autonomously ordered the if / elif dispatch hierarchy strictly by physical wave propagation velocity:

Volcanic Acoustic Shockwaves (traveling at the speed of sound, roughly 310 meters per second) are evaluated first.
Convective Rainstorm Advection (traveling with storm outflows at 10 to 20 meters per second) is evaluated second.
Quasi-Static Tectonic Thermal Diffusion (stationary fault-zone heating approaching 0 meters per second) is evaluated third.

Without being taught geophysical wave mechanics, AlphaEvolve discovered that sorting hazards by propagation speed completely eliminates cross-hazard interference!

8. The Proof: Testing the Autonomously Created Model Across 21 Historical Disasters

A scientific theory is only as good as its empirical predictions. Using 05_predict_multi_hazard.py, we tested the predictive model built by AlphaEvolve's champion algorithm across all 23 historical catalogs (175,363 authentic Netatmo observations).

Figure 9 | Early Warning Paradigm Shift: Performance & Timeline Scorecard. Column 1: Timeline comparison for the 2017 Nerima downpour showing a 34.2-minute lead time (+84.9% longer than manual models). Column 2: Quantitative performance scorecard across all 21 historical disasters (100% sensitivity). Column 3: Control baseline verification confirming 0.0% false alarms and cryptographic SHA-256 data provenance.

Figure 10 | Empirical Verification Results Across 23 Catalogs. (a) Cold pool thermodynamic collapse during the 2017 Nerima rainstorm, achieving 34.2 min lead time. (b) Pre-seismic thermal anomaly 6.0 hours before the 2018 Osaka M5.6 earthquake under perfect isobaric calm. (c) Volcanic Lamb wave linear moveout across 598 Netatmo stations during the 2018 Kusatsu-Shirane eruption (apparent speed 310.64 m/s, R-squared 0.985). Lower panels: 100% sensitivity table, normalized confusion matrix showing 0.0% false alarms, and cryptographic SHA-256 verification.

Dissecting the Empirical Scorecard (Figure 9 & Figure 10)

The quantitative verification results shown in Figure 9 and Figure 10 confirm the power of the AI-constructed predictive model:

Convective Torrential Rainstorms (15 of 15 Detected — 100% Sensitivity): As shown in Column 1 of Figure 9 and the time-series plot in Figure 10(a), during the ferocious 2017 Nerima guerrilla rainstorm in Tokyo, the evolved model triggered a high-confidence alert 34.2 minutes before peak torrential rainfall. Compared to my manual UHC model (18.5 minutes) and official weather radar (which only detects precipitation 5 minutes prior once heavy droplets have already formed aloft), AlphaEvolve extended the life-saving evacuation window by +84.9% (+15.7 extra minutes). Across all 15 rainstorm catalogs, average lead time rose from 19.6 minutes to 36.3 minutes.
Major Inland Earthquakes (4 of 4 Detected — 100% Sensitivity): As shown in Figure 10(b), prior to the destructive 2018 Osaka-North Earthquake (magnitude 5.6), the dynamic isobaric gate detected an intense 38-Kelvin equivalent potential temperature anomaly 6.0 hours before the mainshock. Throughout that window, barometric pressure variation remained below 0.5 hectopascals per hour, confirming lithospheric LAIC origin. All four major earthquakes (2016 Kumamoto, 2018 Osaka, 2018 Hokkaido Iburi, and 2021 Fukushima) were detected with 100% sensitivity.
Explosive Volcanic Eruptions (2 of 2 Detected — 100% Sensitivity): During the 2018 Kusatsu-Shirane eruption (Figure 10c), 598 Netatmo stations captured the expanding acoustic Lamb wave at an empirical speed of 310.64 meters per second (R-squared of 0.985). Array semblance coherence reduced crater back-azimuth localization error from 1.78 degrees down to 0.33 degrees—an 81.5% improvement in directional precision.
Control Baseline Periods (0 False Alarms — 0.0% False Positive Rate): As shown in Column 3 of Figure 9 and the confusion matrix in Figure 10 (bottom center), when tested against calm summer heatwaves and violent winter bomb cyclones, the model produced zero false alarms (0.0% FPR)—completely eradicating the 6.8% false-alarm rate of my earlier manual earthquake model.

9. A Paradigm Shift in Science: Human Craftsmanship vs. Autonomous AI Closed-Loop

Stepping back from the numbers, this experiment demonstrates a profound transformation in how humanity can build scientific models and theories.

Figure 11 | Four-Domain Deep Comparison: Prior Manual Frameworks vs. AlphaEvolve Unified Theory. Visualizing the transition from fragile human-written step heuristics to AI-discovered continuous manifolds across rainstorms (Row 1), earthquakes (Row 2), volcanic eruptions (Row 3), and operational system architectures (Row 4).

Comparing Human Algorithms vs. AI-Created Algorithms (Figure 11)

Figure 11 contrasts my four years of manual model building against the unified algorithm autonomously created by AlphaEvolve:

Row 1 (Rainstorms): Human-written step thresholds missed early moist destabilization (18.5 min lead time). AlphaEvolve autonomously created a continuous logistic enthalpy kernel, expanding lead time to 34.2 min (+84.9%).
Row 2 (Earthquakes): Human scalar thresholds suffered a 6.8% false-alarm rate during storms. AlphaEvolve invented the kinematic-barometric orthogonality gate (|dP/dt| <= 2.0), achieving a 0.0% false-alarm rate.
Row 3 (Volcanoes): Single-station moveout suffered from wind scattering (1.78-degree error). AlphaEvolve integrated multi-channel semblance coherence, sharpening crater localization to 0.33 degrees (-81.5% error).
Row 4 (System Architecture): Four conflicting, slow manual scripts were unified into a single sub-millisecond wave-speed dispatcher with zero alert collisions.

Figure 12 | Scientific Workflow Paradigm Shift: Traditional Manual Pipeline vs. Autonomous AI Closed-Loop. Top (Amber): Months of manual data collection, intuition-based formula drafting, spreadsheet slider tuning, and isolated silo deployment. Bottom (Neon Green): Automated IoT tensor caching, sub-second Gemini 3.8 Flash AST algorithm creation, ruthless Popperian falsification, and unified theory synthesis.

Deconstructing the Workflow Revolution (Figure 12)

Look at the contrast between the two workflows in Figure 12:

The Traditional Human-Centric Pipeline (Figure 12, Top Row in Amber): For centuries, a scientist had to manually gather fragmented datasets, guess mathematical formulas by intuition, spend months adjusting threshold sliders in spreadsheets, and publish isolated models that broke down when phenomena overlapped.
The Autonomous AlphaEvolve Closed Loop (Figure 12, Bottom Row in Neon Green): In this new paradigm, the human researcher defines the physical observables, locks the empirical data into read-only tensors, and sets the Popperian falsification rules (-5,000 points per false alarm). Then, AlphaEvolve and Gemini autonomously write and evolve the algorithms to construct the predictive model. Finally, the human scientist reads the winning white-box code to formalize a unified physical theory.

10. The Future of AlphaEvolve and Autonomous Theory Construction

We are standing at the threshold of a new Renaissance in empirical science.

By proving that AlphaEvolve can take 175,363 noisy citizen weather observations and autonomously create the algorithms that build the predictive model and establish a unified multi-hazard disaster theory, we have unlocked a blueprint that extends far beyond meteorology and seismology:

Climate Science & Sub-Grid Physics: Autonomously discovering symbolic cloud microphysics and ocean turbulence closures from satellite telemetry.
Clean Energy & Materials Science: Evolving explicit mathematical transport models for solid-state battery electrolytes and photovoltaic stability.
Fusion Energy: Discovering ultra-fast, sub-millisecond white-box control algorithms for magnetic plasma confinement in tokamak reactors.
Biomedicine: Synthesizing interpretable mathematical models of cellular signaling pathways from multi-omics datasets.

A Final Message to Developers, Scientists, and Dreamers

To my fellow developers and researchers: AI is not here to replace the human scientist.

AlphaEvolve did not replace me; it liberated me. It took the exhausting, error-prone burden of manual algorithm writing, parameter tuning, and trial-and-error off my shoulders, allowing me to focus on physical architecture, data integrity, and theoretical synthesis.

Nature has spent billions of years weaving intricate physical laws across the Earth and the cosmos. Today, for the first time in history, we have an intelligent partner capable of listening to the digital whispers of thousands of balcony sensors, autonomously writing the mathematical algorithms to model them, and helping us discover the laws of nature to protect human lives.

Read the Full Open-Access Paper & Explore the Sample Scripts

For the complete mathematical derivations, the 4-stage AlphaEvolve discovery architecture, the full empirical verification results across all 23 historical catalogs, and the sample Python scripts, please visit our open-access paper on Zenodo [10] and our GitHub repository:

Paper Title: Autonomous Discovery of Unified Multi-Hazard Prediction Theory from Netatmo IoT Weather Big Data Using AlphaEvolve
Author: Kanshi Tanaike
Zenodo Open-Access URL: https://zenodo.org/records/23354598
Sample Scripts Repository (GitHub): https://github.com/tanaikech/alphaevolve-multi-hazard

References

[1] Bolton, D. (1980). The computation of equivalent potential temperature. Monthly Weather Review, 108(7), 1046–1053.

[2] Matoza, R. S., et al. (2022). Atmospheric waves and global seismoacoustic observations of the January 2022 Hunga eruption, Tonga. Science, 377(6601), 95–100.

[3] Napoly, A., et al. (2018). Development and application of a crowdsourced weather station quality control tool: Netatmo station dataset in Berlin. Frontiers in Earth Science, 6, 118.

[4] Pulinets, S., & Ouzounov, D. (2011). Lithosphere-Atmosphere-Ionosphere Coupling (LAIC) model: An unified concept for earthquake precursors validation. Journal of Asian Earth Sciences, 41(4–5), 371–382.

[5] Romera-Paredes, B., et al. (2024). Mathematical discoveries from program search with large language models. Nature, 625(7995), 468–475.

[6] Tanaike, K. (2026a). Early Detection of Guerrilla Rainstorms from Crowdsourced IoT Weather Networks: The Urban Heat Convection (UHC) Thermodynamic Framework. ESS Open Archive.

[7] Tanaike, K. (2026b). Direct Pre-Seismic Precursor Detection from Crowdsourced IoT Atmospheric Sensor Networks: Theoretical Unification with Lithosphere-Atmosphere-Ionosphere Coupling (LAIC). ESS Open Archive.

[8] Tanaike, K. (2026c). Volcanic Explosion and Infrasonic Lamb Wave Moveout Analysis via Dense Crowdsourced IoT Barometric Sensor Networks. ESS Open Archive.

[9] Tanaike, K. (2026d). Micro-Scale Convective Rain Prediction via High-Density IoT Weather Sensor Networks and Localized Fluid Dynamics. ESS Open Archive.

[10] Tanaike, K. (2026e). Autonomous Discovery of Unified Multi-Hazard Prediction Theory from Netatmo IoT Weather Big Data Using AlphaEvolve. Zenodo. https://zenodo.org/records/23354598

Taking Advantage of Cloud Run Sandboxes with Google Apps Script for Google Workspace

Tanaike — Thu, 10 Sep 2026 02:43:19 +0000

Deterministic Sub-Second Python and Bash Execution, Zero-Trust gVisor Isolation, and Zero Idle Cost

Abstract

While secure sandboxes are pivotal for running Generative AI-generated code safely, connecting Google Cloud Run Sandboxes (gVisor) directly to Google Apps Script unlocks a vastly broader horizon. Beyond executing AI-drafted scripts on the fly, this complementary architecture empowers Google Workspace with deterministic Python data science (Pandas, Seaborn) and Bash execution in 200–450 ms. With zero-trust micro-isolation, zero-token data ingestion, and zero idle cost, it elevates Workspace automations far beyond standard V8 runtime constraints.

Introduction

Google Apps Script (GAS) Ref is a cornerstone of Google Workspace automation across Sheets, Docs, Forms, and Drive. Yet, developers often hit hard limits. Standard accounts enforce a strict 6-minute timeout. The environment runs only JavaScript on V8, precluding native Linux binaries or external compilers. When an unhandled exception occurs, the entire script halts abruptly.

Recently, in my article "Taking Advantage of Gemini Managed Agents with Google Apps Script" Ref, I showed how to break past these limits by connecting Apps Script to a persistent Linux sandbox provisioned by Gemini Managed Agents Ref. Using my Go CLI tool ggsrun Ref for direct streaming between the sandbox and Google Drive, that architecture handles heavy, multi-turn agentic workflows. Examples include Playwright scraping across multiple viewports and audio transcoding with FFmpeg.

Gemini Managed Agents excel at autonomous, multi-step reasoning. However, they rely on LLM prompts via the Interactions API. This adds conversational inference overhead, pushing response latencies to several seconds or tens of seconds while burning token quotas (such as 200k TPM) Ref. Many everyday Workspace automations do not need an LLM. Tasks like mathematical evaluations, string parsing, regular expression matching, and shell commands require deterministic, instant execution without prompt ambiguity or token limits.

The breakthrough moment came when I encountered Romin Irani's masterfully crafted and inspiring article, "Safely Running Untrusted Code: A Hands-On Guide to Google Cloud Run Sandboxes" Ref. In his exceptional guide, Irani brilliantly illuminated how Google Cloud Run Sandboxes leverage gVisor application kernel technology to deliver lightweight, ephemeral micro-isolation for arbitrary code execution with remarkable simplicity and elegance. Reading his hands-on exploration sparked an immediate insight: What if we connect this powerful sandbox directly to Google Apps Script? Could this be the key to supercharging Google Workspace automations with instant, secure dynamic execution? That spark inspired me to plan, design, and thoroughly refine the project presented here.

Fundamentally, secure sandboxes have become an indispensable cornerstone in the era of Generative AI. When large language models like Gemini generate code on the fly, they produce untrusted scripts that demand strict execution isolation to shield host environments from unintended side effects, resource exhaustion, or security compromises. I myself have continuously explored and proposed sandboxing approaches for Google Apps Script to safely execute AI-generated code Ref, Ref. Yet, liberating this sandboxed execution capability so that it can be directly orchestrated from Google Apps Script unlocks a vastly broader horizon. It transforms Apps Script from a bounded JavaScript runtime into an agile command center. Beyond safely running AI-generated scripts in real time, it empowers Google Workspace to seamlessly offload high-performance Python and Bash workloads—spanning advanced statistics, scientific plotting with Pandas and Seaborn, and complex data transformations—that were previously unattainable within Apps Script alone.

In this article, I introduce this complementary architecture powered by Google Cloud Run Sandboxes (--sandbox-launcher) Ref. By pairing gVisor Ref micro-virtualization with second-generation Cloud Run instances Ref, Apps Script can dispatch dynamic Python and Bash scripts over standard REST HTTP calls. The benefits are clear: sub-second execution (200 to 450 ms), zero-trust process isolation, and zero idle maintenance costs. Together, Cloud Run Sandboxes and Gemini Managed Agents give developers a comprehensive automation toolkit for Google Workspace.

Architecture: Cloud Run Sandboxes for Google Apps Script

Cloud Run Sandboxes compartmentalize untrusted code execution using gVisor application kernel technology. Integrating this infrastructure with Google Apps Script offers four major benefits:

Figure 1: Architectural workflow linking Google Apps Script, Cloud Run FastAPI Runner, and gVisor Micro-Sandbox.

Dynamic code execution without image rebuilding: You never need to rebuild or redeploy container images when script logic changes. Apps Script dynamically generates Python or Bash code strings and posts them to the Cloud Run runner for immediate execution.
Crash resilience against runaway scripts: If an offloaded script triggers a segmentation fault or an infinite loop (while True: pass), gVisor isolates and terminates only the child process via SIGKILL. The parent FastAPI runner remains healthy and returns a clean JSON error response.
Deterministic sub-second latency: Because the sandbox forks directly inside a running container, it avoids cold VM boots and prompt delays, running guest code in 200 to 450 milliseconds.
Zero-idle cost management: Setting --min-instances=0 allows Cloud Run to scale to zero when idle. Combined with Google Cloud's Always Free tier Ref, everyday automation incurs zero idle maintenance cost.

System Architecture and Processing Workflow

The architecture connects three layers: the Google Apps Script orchestrator, the Cloud Run FastAPI proxy runner, and the gVisor micro-sandbox isolation layer. For complete, step-by-step setup and deployment instructions, please refer to the detailed guide in the GitHub Repository.

Execution flows through three sequential stages:

Stage 1: Dispatch from Google Apps Script: Apps Script sends an HTTPS POST request with a JSON payload containing the code snippet, language (Python or Bash), timeout, and security override flags. Core logic is implemented in gas/Code.js and gas/Auth.js.
Stage 2: Execution by FastAPI Proxy Runner: A lightweight Python service on Cloud Run Gen2 (cloud_run/main.py) receives the payload. It invokes /usr/local/gcp/bin/sandbox do -- <command>, capturing wall-clock runtime, exit codes, stdout, and stderr.
Stage 3: Ephemeral isolation in gVisor: The gVisor sandbox intercepts every guest system call. It blocks access to the Google Cloud Metadata Server (169.254.169.254) to eliminate SSRF risks, strips host environment variables, enforces a read-only root filesystem, and shuts down external network egress by default.

8-Axis Verification Suite from Google Apps Script

To verify both functional accuracy and security boundaries, I designed and executed an 8-axis test suite directly from Google Apps Script.

Figure 2: Comprehensive 8-axis test suite matrix evaluating deterministic execution and security isolation.

The complete suite is implemented in gas/TestCases.js. The core verification logic includes:

TC-01: Basic Computation: Evaluates deterministic Python arithmetic (print(2**32)). Expected result: 4294967296 with exit code 0. Full test definition: gas/TestCases.js:TC-01.
TC-02: Syntax Error Handling: Injects an invalid syntax payload (print('unclosed string literal) to verify crash resistance. Expected result: Structured error JSON containing SyntaxError without container failure. Full test definition: gas/TestCases.js:TC-02.
TC-03: Infinite Loop DoS Defense: Runs an infinite loop (while True: pass) with a 2.0-second timeout. Expected result: gVisor terminates the guest process cleanly after 2.0 seconds via SIGKILL. Full test definition: gas/TestCases.js:TC-03.
TC-04: Metadata Server SSRF Isolation: Probes 169.254.169.254 to attempt service account token extraction. Expected result: Request blocked with Network is unreachable. Full test definition: gas/TestCases.js:TC-04.
TC-05: Host Environment Variable Shielding: Dumps guest environment variables to check host credential leakage. Expected result: GCP credentials and host variables are completely absent. Full test definition: gas/TestCases.js:TC-05.
TC-06: Filesystem Write Protection: Attempts to write to the container root filesystem. Expected result: Blocked with Read-only file system by default; allowed only in isolated tmpfs with --write. Full test definition: gas/TestCases.js:TC-06.
TC-07: Outbound Network Egress Isolation: Attempts an outbound TCP connection to public DNS (1.1.1.1:53). Expected result: Connection rejected by default; allowed only with --allow-egress. Full test definition: gas/TestCases.js:TC-07.
TC-08: Isolated Bash Subshell Execution: Runs uname -a && id in a Bash subshell. Expected result: Returns the kernel signature 4.19.0-gvisor, confirming gVisor containment. Full test definition: gas/TestCases.js:TC-08.

Execution Log and Verification Results

The following execution log was captured directly from the Google Apps Script logger during my verification run. Project hashes are sanitized as [PROJECT-HASH], container UUIDs are sanitized as [INSTANCE-UUID], and timestamps are normalized to start at 00:00:00:

00:00:00    Notice  Execution started
00:00:00    Info    ================================================================================
00:00:00    Info    STARTING CLOUD RUN SANDBOX TEST SUITE (GAS EXECUTION)
00:00:00    Info    Target Base URL: https://cr-gas-sandbox-[PROJECT-HASH]-uc.a.run.app
00:00:00    Info    Started At     : 2026-09-09T00:00:00.000Z
00:00:00    Info    ================================================================================
00:00:00    Info    Executing [TC-01] Basic Python Computation (2**32)...
00:00:04    Info    Executing [TC-02] Syntax Error Handling & Crash Resistance...
00:00:05    Info    Executing [TC-03] Infinite Loop DoS Defense (Timeout Enforcement)...
00:00:07    Info    Executing [TC-04] Metadata Server SSRF Isolation (169.254.169.254)...
00:00:08    Info    Executing [TC-05] Host Environment Variable Shielding...
00:00:09    Info    Executing [TC-06] Filesystem Write Protection (Ephemeral tmpfs)...
00:00:10    Info    Executing [TC-07] Outbound Network Egress Isolation...
00:00:12    Info    Executing [TC-08] Isolated Bash Subshell Command Execution...
00:00:13    Info
### 📊 CLOUD RUN SANDBOX × GAS VERIFICATION RUN REPORT

- Total Tests Executed: 8
- Passed: 8 / 8
- Failed: 0 / 8
- Total Execution Wall Time: 12.44 seconds
- Overall Verdict: ✅ ALL TESTS PASSED

| Test ID | Test Name | HTTP | Server Time | Network RTT | Sandbox Active | Status |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
| **TC-01** | Basic Python Computation (2**32) | 200 | 449.34 ms | 3609 ms | gVisor (True) | ✅ PASS |
| **TC-02** | Syntax Error Handling & Crash Resistance | 200 | 201.43 ms | 322 ms | gVisor (True) | ✅ PASS |
| **TC-03** | Infinite Loop DoS Defense (Timeout Enforcement) | 200 | 2003.96 ms | 2118 ms | gVisor (True) | ✅ PASS |
| **TC-04** | Metadata Server SSRF Isolation (169.254.169.254) | 200 | 716.68 ms | 874 ms | gVisor (True) | ✅ PASS |
| **TC-05** | Host Environment Variable Shielding | 200 | 411.31 ms | 539 ms | gVisor (True) | ✅ PASS |
| **TC-06** | Filesystem Write Protection (Ephemeral tmpfs) | 200 | 641.73 ms | 757 ms | gVisor (True) | ✅ PASS |
| **TC-07** | Outbound Network Egress Isolation | 200 | 992.04 ms | 1106 ms | gVisor (True) | ✅ PASS |
| **TC-08** | Isolated Bash Subshell Command Execution | 200 | 338.78 ms | 460 ms | gVisor (True) | ✅ PASS |

#### 📝 Detailed Execution Breakdown & Raw Outputs

--------------------------------------------------------------------------------
[TC-01] Basic Python Computation (2**32)
Endpoint       : /run
Verdict        : PASS - Correct computation result returned (4294967296)
Timing         : Server=449.34ms, RoundTrip=3609ms
Sandbox Active : true
stdout         : 4294967296
--------------------------------------------------------------------------------
[TC-02] Syntax Error Handling & Crash Resistance
Endpoint       : /run
Verdict        : PASS - Container remained healthy, structured error JSON safely returned
Timing         : Server=201.43ms, RoundTrip=322ms
Sandbox Active : true
stderr         : SyntaxError: unterminated string literal (detected at line 1)
--------------------------------------------------------------------------------
[TC-03] Infinite Loop DoS Defense (Timeout Enforcement)
Endpoint       : /run
Verdict        : PASS - Process terminated cleanly after 2.0s without hanging server
Timing         : Server=2003.96ms, RoundTrip=2118ms
Sandbox Active : true
stderr         : Execution timed out after 2.0 seconds
--------------------------------------------------------------------------------
[TC-04] Metadata Server SSRF Isolation (169.254.169.254)
Endpoint       : /test/metadata-isolation
Verdict        : PASS - Metadata server unreachable from sandbox (SSRF Blocked)
Timing         : Server=716.68ms, RoundTrip=874ms
Sandbox Active : true
details        : ACCESS_BLOCKED: URLError: <urlopen error [Errno 101] Network is unreachable>
--------------------------------------------------------------------------------
[TC-05] Host Environment Variable Shielding
Endpoint       : /test/env-isolation
Verdict        : PASS - Host GCP credentials and environment variables fully masked
Timing         : Server=411.31ms, RoundTrip=539ms
Sandbox Active : true
details        : Sensitive host environment variables are properly masked from sandbox guest.
--------------------------------------------------------------------------------
[TC-06] Filesystem Write Protection (Ephemeral tmpfs)
Endpoint       : /test/fs-isolation
Verdict        : PASS - Read-only filesystem enforced by default; write permitted only with flag
Timing         : Server=641.73ms, RoundTrip=757ms
Sandbox Active : true
details        : Write blocked without flag: PASS. Write permitted with flag: PASS.
--------------------------------------------------------------------------------
[TC-07] Outbound Network Egress Isolation
Endpoint       : /test/egress-isolation
Verdict        : PASS - Outbound network traffic blocked by default; enabled only with flag
Timing         : Server=992.04ms, RoundTrip=1106ms
Sandbox Active : true
details        : Egress blocked without flag: PASS. Egress allowed with flag: PASS.
--------------------------------------------------------------------------------
[TC-08] Isolated Bash Subshell Command Execution
Endpoint       : /run
Verdict        : PASS - Bash subshell executed securely inside sandbox
Timing         : Server=338.78ms, RoundTrip=460ms
Sandbox Active : true
stdout         : Linux sandbox-[INSTANCE-UUID] 4.19.0-gvisor #1 SMP Sun Jan 10 15:06:54 PST 2016 x86_64 GNU/Linux
--------------------------------------------------------------------------------
00:00:13    Notice  Execution completed

All eight test vectors achieved a 100% PASS rate. In particular, TC-08 explicitly returned the kernel signature 4.19.0-gvisor, confirming gVisor process containment.

Latency and Performance Analysis

Measuring execution telemetry reveals distinct performance profiles between cold starts and warm executions:

Figure 3: Latency breakdown between cold-start container provisioning and warm micro-sandbox execution.

Cold Start Phase (TC-01): Scaling from zero instances, the initial request takes 3,609 ms round-trip time. Cloud Run container provisioning accounts for 3.16 seconds of this time, while the gVisor fork and Python execution take only 449 ms.
Warm Execution Phase (TC-02 to TC-08): Subsequent calls bypass container startup, reducing round-trip latency to 322–539 ms. Server-side sandbox processing remains steady at 201–411 ms.
Minimal Compute Overhead: Because gVisor forks an existing process tree rather than booting an external virtual machine, virtualization overhead stays below 50 ms.

Cost Analysis and Safety Guardrails

Running external cloud services for automation often raises concerns about unexpected billing. In this architecture, costs are bounded by Google Cloud policies Ref and explicit service guardrails:

Figure 4: Google Cloud Always Free tier allocations and zero-idle cost architecture.

Always Free Tier Allocation: Cloud Run provides 2 million requests, 360,000 GiB-seconds of memory, and 180,000 vCPU-seconds free per month Ref. A 0.5-second execution on a 512MiB/1CPU profile allows hundreds of thousands of monthly requests without cost.
Zero-Idle Scaling (--min-instances=0): Cloud Run shuts down all active instances when idle, generating zero compute charges between executions.
Concurrency Guardrails (--max-instances=1): Capping instances at 1 ensures runaway recursive triggers in Apps Script cannot spawn concurrent container fleets.
Hard Timeout Enforcement (--timeout=15s): Cloud Run forcibly terminates any request exceeding 15 seconds, preventing long-running resource drain.
One-Step Cleanup Script: The repository includes scripts/cleanup.sh to delete the Cloud Run service, Artifact Registry images, and temporary Cloud Storage buckets with a single command.

Practical Application: Generating Multivariate Correlation Heatmaps on Google Sheets

While unit tests validate security and latency, the real value of Cloud Run Sandboxes emerges in solving everyday Google Workspace challenges that Apps Script cannot address natively.

A prime example is advanced scientific visualization. While Google Sheets provides standard bar and line charts, it completely lacks native support for bivariate or multivariate statistical visualizations—such as Pearson correlation matrix heatmaps, kernel density estimates, or regression confidence bands. Traditionally, developers were forced to either export datasets to external desktop environments or configure cumbersome third-party visualization services.

By combining Google Apps Script with Cloud Run Sandboxes, developers can bridge this gap seamlessly:

Automated Sheet Population: Apps Script creates a new Google Spreadsheet and populates it with a multivariate table (for example, academic evaluation scores across Math, Physics, Chemistry, English, and History).
Dynamic Script Formulation: Apps Script extracts the numeric matrix and pairs it with a Python script utilizing pandas, matplotlib, and seaborn.
Sub-Second gVisor Execution: The payload is dispatched to Cloud Run Sandboxes (POST /run). Inside the isolated micro-sandbox, Python computes the correlation matrix (df.corr()) and renders a publication-grade heatmap PNG directly into a Base64 string in ~350 ms.
Direct Blob Insertion: Apps Script decodes the Base64 output into a native image Blob (Utilities.newBlob()) and embeds it directly beside the dataset on the Google Sheet (sheet.insertImage()).

The Dynamic Python Visualization Script

In gas/PracticalDemo.js, Apps Script dynamically constructs and dispatches the following Python script to the Cloud Run runner:

import os
os.environ['MPLCONFIGDIR'] = '/tmp/mpl'
import io, json, base64
import matplotlib
matplotlib.use('Agg')
import matplotlib.pyplot as plt
import pandas as pd
import seaborn as sns

# Injected empirical dataset from Google Sheets
records = [
  {"Math": 95, "Physics": 92, "Chemistry": 88, "English": 72, "History": 68},
  # ... (15 rows injected dynamically from spreadsheet)
]
df = pd.DataFrame(records)

# Calculate Pearson correlation matrix
corr = df.corr()

# Configure publication-grade styling
plt.figure(figsize=(6.8, 5.2), dpi=150)
sns.set_theme(style='white')
cmap = sns.diverging_palette(230, 20, as_cmap=True)
ax = sns.heatmap(corr, annot=True, fmt='.2f', cmap=cmap, vmin=-1.0, vmax=1.0,
                 square=True, linewidths=0.6, cbar_kws={'shrink': 0.8})
plt.title('Student Performance: Multivariate Correlation Heatmap', fontsize=11, fontweight='bold', pad=12)
plt.tight_layout()

# Encode plot to Base64 PNG buffer
buf = io.BytesIO()
plt.savefig(buf, format='png', dpi=150)
plt.close()
buf.seek(0)
b64_png = base64.b64encode(buf.getvalue()).decode('utf-8')

# Output structured JSON to stdout
print(json.dumps({
    'status': 'success',
    'image_base64': b64_png,
    'variables': list(df.columns),
    'records_processed': len(df)
}))

This Python script is engineered with four deliberate architectural techniques:

gVisor Read-Only Filesystem Adaptation (MPLCONFIGDIR): In Cloud Run Sandboxes, gVisor enforces a strict read-only root filesystem (/) to defend against tampering. Under normal circumstances, Matplotlib attempts to create a font cache in ~/.config/matplotlib, throwing write permission warnings or errors. Setting os.environ['MPLCONFIGDIR'] = '/tmp/mpl' redirects cache writes to the ephemeral, writable /tmp (tmpfs) directory, ensuring clean, warning-free execution with empty stderr.
Headless In-Memory Image Rendering: Setting matplotlib.use('Agg') and utilizing an in-memory io.BytesIO() buffer completely eliminates disk I/O. The chart is rendered in memory, encoded into Base64, and recycled immediately, delivering sub-second execution speeds without leaving stale files on disk.
Structured Stdout Communication Protocol: The script outputs a single, structured JSON payload to stdout containing the Base64 image and processing metadata. Apps Script parses this response effortlessly, requiring no complex multi-part MIME decoding or secondary storage buckets.
Direct Empirical Data Injection: Tabular data extracted from Google Sheets is serialized as JSON and directly embedded into the guest script template. This allows arbitrary row counts and columns to be processed without requiring database drivers or network connections inside the sandbox.

Dynamic Script Generation via Gemini API

An essential architectural advantage of this setup is that the Python script does not need to be hard-coded. Developers can call the Gemini API directly from Apps Script with a natural language prompt—such as "Generate a Python Seaborn script to compute a correlation heatmap from this JSON table and output Base64 PNG"—to dynamically synthesize the visualization code on demand.

This workflow unlocks a powerful synergy:

Gemini (Single-Turn Code Generation): Formulates tailored data transformation and plotting logic from high-level natural language instructions.
Cloud Run Sandboxes (Instant Deterministic Execution): Runs the generated Python code inside an ephemeral gVisor micro-sandbox at sub-second speeds (200–450 ms), completely shielding Google Workspace from untrusted code execution while incurring zero idle hosting cost.

Operational Advantages over Gemini Managed Agents

In my previous article, Taking Advantage of Gemini Managed Agents with Google Apps Script, Gemini Managed Agents provisioned a heavy-duty container (4 vCPU / 16 GB RAM) with a multi-hour persistent session. That architecture excels at exploratory, conversational agentic workflows where the agent navigates ambiguous tasks and self-heals over multiple turns.

However, for automated spreadsheet recalculation, scheduled batch reporting, or user-facing UI triggers, Cloud Run Sandboxes provides a distinctly superior operational profile:

Sub-Second Execution Speed: Cloud Run Sandboxes renders and returns the chart in ~350 ms, compared to 15–30+ seconds for conversational LLM agent reasoning.
Compatibility with Google Sheets Custom Functions (30-Second Limit): Google Sheets custom functions (formula functions called directly from cells) enforce a rigid, non-negotiable 30-second execution timeout. In the Gemini Managed Agents architecture, having a generative AI model in the loop creates conversational inference overhead that frequently pushes turnaround times to 15–40+ seconds, making it ill-suited for in-cell custom formulas. In contrast, Cloud Run Sandboxes deliver deterministic sub-second responses (200–450 ms), operating well below the 30-second ceiling. This low latency makes it effortless to create dynamic, cell-level custom functions powered by Python (such as statistical modeling, complex regex transformations, or matrix operations) that update smoothly as spreadsheet data changes.
Zero-Token High-Volume Data Ingestion: Sends thousands of spreadsheet rows, raw arrays, or megabytes of JSON directly over standard HTTP payloads without consuming LLM input tokens, completely removing TPM rate-limit anxiety and payload token costs.
Zero Cost and Generous Quotas: Cloud Run Sandboxes consumes no LLM tokens and operates entirely within Cloud Run's generous Always Free tier.
Deterministic Mathematical Precision: The statistical calculations and graphical outputs are 100% deterministic and reproducible, eliminating prompt hallucinations.

The implementation is available in the repository as gas/PracticalDemo.js. To support Google Sheets creation and image embedding, ensure your appsscript.json includes the "https://www.googleapis.com/auth/spreadsheets" and "https://www.googleapis.com/auth/drive" OAuth scopes as documented in gas/setup_instructions.md.

Figure 5: Google Sheets generated with multivariate student data and an embedded correlation heatmap rendered by Cloud Run Sandboxes (Matplotlib & Seaborn).

Real-World Execution Telemetry and Perceptual Performance

When executing runPracticalHeatmapDemo() directly from Google Apps Script, the perceptual speed is electrifying. The actual execution log demonstrates this seamless end-to-end flow:

00:00:01    Notice  Execution started
00:00:02    Info    ================================================================================
00:00:02    Info    STARTING PRACTICAL DEMO: SPREADSHEET HEATMAP VIA CLOUD RUN SANDBOX
00:00:02    Info    Target Base URL: https://cr-gas-sandbox-[PROJECT-HASH]-uc.a.run.app
00:00:02    Info    Started At     : 2026-09-09T00:00:02.275Z
00:00:02    Info    ================================================================================
00:00:02    Info    [Step 1/4] Creating new Google Spreadsheet with multivariate student metrics...
00:00:04    Info    Spreadsheet created: https://docs.google.com/spreadsheets/d/[SPREADSHEET-ID]/edit
00:00:04    Info    [Step 2/4] Reading data from Sheet and constructing JSON matrix payload...
00:00:04    Info    Extracted 15 rows across 5 variables.
00:00:04    Info    [Step 3/4] Dispatching payload to Cloud Run Sandboxes (POST /run)...
00:00:08    Info    Sandbox Server Time : 4161.7 ms
00:00:08    Info    Network Round-Trip  : 4343 ms
00:00:08    Info    Is Sandboxed (gVisor): true
00:00:08    Info    [Step 4/4] Converting Base64 output to Blob and embedding onto Google Sheet...
00:00:09    Info    ================================================================================
00:00:09    Info    DEMO COMPLETED SUCCESSFULLY!
00:00:09    Info    Spreadsheet URL : https://docs.google.com/spreadsheets/d/[SPREADSHEET-ID]/edit
00:00:09    Info    Execution Time  : Server 4161.7 ms | Total 4343 ms
00:00:09    Info    ================================================================================
00:00:10    Notice  Execution completed

The entire pipeline—creating a new Google Spreadsheet, styling header rows, reading data back, dispatching across HTTPS to Cloud Run, cold-loading heavy scientific libraries (pandas, numpy, matplotlib, seaborn) inside a gVisor micro-sandbox, calculating Pearson correlation coefficients, rendering the plot, streaming the Base64 PNG back, decoding into a Blob, and embedding it into the Sheet—finished in just 9 seconds of total wall-clock time (with only 4.16 seconds of Cloud Run server compute).

Visual Layout and Analytical Fidelity

Examining the resulting Google Sheet (Figure 5) reveals exceptional publication quality:

Tabular Matrix (Columns A–F): 15 student records populated across 5 academic disciplines (Math, Physics, Chemistry, English, and History) with styled blue headers and clean grid alignment.
Embedded Chart (Columns H–L): The 5x5 Pearson correlation matrix rendered by Seaborn using a diverging palette (coolwarm) with explicit correlation coefficients and colorbar (-1.00 to +1.00).
Domain Insights: STEM subjects (Math, Physics, Chemistry) display strong positive clustering (> 0.94), while humanities (English, History) correlate at 0.99. Cross-domain pairs exhibit sharp negative divergence (-0.95 to -0.99), delivering instant statistical clarity.
Perceptual Speed Leap: Compared to Gemini Managed Agents, which typically requires 30 to 60+ seconds for conversational reasoning and container bootstrapping, Cloud Run Sandboxes feels instantaneous. For spreadsheet users, waiting 8–9 seconds for a full end-to-end spreadsheet creation and visual chart generation is a revolutionary leap in developer experience.

Comparing Cloud Run Sandboxes and Gemini Managed Agents

Choosing between these two technologies from Google Apps Script requires evaluating the fundamental trade-offs between autonomous artificial intelligence and deterministic high-speed computation:

Figure 6: Strategic workload comparison: Cloud Run Sandboxes vs. Gemini Managed Agents.

Figure 7: Detailed compute specifications, hardware profiles, and session lifecycle comparison.

Workload Intent and Reasoning: Cloud Run Sandboxes Ref target deterministic, high-speed code execution under strict isolation. In contrast, Gemini Managed Agents Ref handle autonomous workflows requiring natural language reasoning, multi-step problem solving, and dynamic package installation.
Execution Trigger: Cloud Run Sandboxes take raw code strings over standard REST HTTP POST requests from Apps Script. Gemini Managed Agents require natural language prompts via the Interactions API.
Latency Profiles: Cloud Run Sandboxes deliver sub-second responses (200 to 450 ms server execution). Gemini Managed Agents incur conversational LLM inference delays of several to tens of seconds.
Hardware Specifications and Compute Resources: Cloud Run Sandboxes are deployed on an agile, minimal compute profile (1 vCPU / 512 MiB RAM in this architecture, scalable up to 8 vCPU / 32 GB), minimizing virtualization overhead and maximizing Always Free tier mileage. In contrast, Gemini Managed Agents provision a heavy-duty container profile (4 vCPU / 16 GB RAM) capable of supporting large browser engines (Playwright/Chromium) and media encoding toolchains (FFmpeg).
Session Lifetime and Execution Duration (TTL): Cloud Run Sandboxes operate under an ephemeral, request-scoped lifecycle (sub-second execution with a strict 15-second Cloud Run hard cap), instantly destroying all in-memory tmpfs state upon request completion and scaling to zero instances when idle. In contrast, Gemini Managed Agents provide a persistent multi-turn session lifecycle (environmentId) with a TTL lasting several hours, allowing installed tools and shared disk state to survive across multiple interactions.
Data Payload Ingestion and Token Freedom: Cloud Run Sandboxes ingests multi-megabyte raw JSON or binary Base64 streams directly over standard HTTP (up to 32 MB) with zero token consumption and zero rate-limit constraints. In contrast, feeding high-volume tabular datasets or multi-megabyte dumps into Gemini Managed Agents consumes thousands of input tokens per interaction, rapidly exhausting 200k TPM quotas and risking context window saturation.
Pricing and Quotas: Cloud Run Sandboxes use standard compute billing, remaining comfortably within free tiers for typical automation tasks. Gemini Managed Agents consume LLM tokens subject to TPM limits (such as 200k TPM) Ref.
State Persistence: Cloud Run Sandboxes remain strictly ephemeral, recycling the environment after each run. Gemini Managed Agents offer persistent workspaces (environmentId) to retain files and installed packages.

Architectural Trade-offs: Advantages and Limitations

Understanding the practical strengths and weaknesses of each runtime ensures optimal architectural decisions:

Cloud Run Sandboxes Advantages: Delivers deterministic sub-second execution (200 to 450 ms) with 100% mathematical precision and zero prompt ambiguity. Ingests high-volume tabular arrays directly over HTTP with zero token consumption, completely bypassing TPM rate limits. Generates zero idle hosting expenses through automatic scale-to-zero, staying well within the Always Free tier of 2 million monthly requests.
Cloud Run Sandboxes Limitations: Purely ephemeral with no cross-request file or package persistence. Resource-constrained by default (512 MiB RAM / 1 vCPU) and strictly capped by a 15-second timeout, making it unsuitable for multi-hour sessions or heavyweight browser instances.
Gemini Managed Agents Advantages: Provides unmatched adaptability when the code or solution is not known in advance. Natural language instructions enable the agent to write its own scripts, inspect errors, self-heal, and dynamically install Linux packages inside a heavy-duty 16 GB container that persists across multiple turns.
Gemini Managed Agents Limitations: Suffers from conversational inference latency (often 10 to 30+ seconds), potential output non-determinism, and token quota exhaustion (200k TPM) during high-frequency invocation. It is ill-suited for real-time user-facing spreadsheet UI interactions.

Practical Scenarios: When to Use Which Architecture

To maximize automation efficiency in Google Workspace, consider these proven deployment scenarios:

Scenario 1: High-Frequency Spreadsheet Recalculation and Custom Functions (Use Cloud Run Sandboxes): When building in-cell Google Sheets custom functions (such as =PY_EVAL(...)) or triggering onEdit events to perform numerical optimization, Monte Carlo simulations, or matrix operations across thousands of rows. Because Google Sheets enforces a rigid 30-second timeout on custom functions, Gemini Managed Agents' generative AI inference latency (15–40+ seconds) is ill-suited for this use case. Cloud Run Sandboxes return accurate results in ~300 ms, fitting comfortably within the 30-second limit and updating spreadsheet cells instantaneously without token costs.
Scenario 2: Dynamic Multi-Page Headless Browser Scraping (Use Gemini Managed Agents): When automating the extraction of dynamically rendered JavaScript tables across authenticated web portals using Playwright and Chromium. The 4 vCPU / 16 GB RAM environment and persistent filesystem allow the agent to manage browser cookies, navigate pages, and stream screenshots or PDF deliverables directly to Google Drive via ggsrun.
Scenario 3: Secure Data Transformation and Format Parsing (Use Cloud Run Sandboxes): When processing automated Google Forms submissions containing raw text, structured CSVs, or proprietary logs that require regular expression extraction, cryptographic hashing, or data validation. Cloud Run Sandboxes execute thousands of deterministic invocations daily within the Always Free tier without risking prompt hallucinations.
Scenario 4: Exploratory Research and Open-Ended Data Synthesis (Use Gemini Managed Agents): When an analyst uploads an unstructured data dump to Google Drive and asks the system to identify anomalies, formulate ad-hoc Python visualizations, and draft an executive narrative summary. The agent's autonomous reasoning and multi-turn persistence excel at iterating until high-level analytical goals are met.

Summary

In this article, I demonstrated how to integrate Google Apps Script with Google Cloud Run Sandboxes to run dynamic Python and Bash workloads securely, deterministically, and with blistering speed. By offloading compute tasks to gVisor micro-sandboxes, Google Workspace automations gain the power to safely execute AI-generated scripts on demand and perform advanced data science without server maintenance overhead.

Key takeaways from this implementation:

Eliminated runtime limits and enabled safe AI code execution: Executed arbitrary Python and Bash scripts on demand without container rebuilding, allowing Apps Script to safely run Gemini-generated logic and native data science libraries (Pandas, Seaborn).
Achieved blistering perceptual speed and sub-second latency: Recorded 200–450 ms server execution speeds and completed an end-to-end spreadsheet visualization demo in just 9.0 seconds, delivering responsiveness orders of magnitude faster than multi-turn LLM agents.
Enabled zero-token high-volume data exchange: Streamed tabular data and images directly over standard HTTP payloads, completely bypassing LLM context windows, token billing, and 200k TPM rate limit bottlenecks.
Validated 4-axis zero-trust micro-isolation: Confirmed empirical protection via gVisor against SSRF metadata extraction, host environment variable leaks, root filesystem modifications, and unauthorized network egress.
Established zero-idle operations and strategic synergy: Maintained $0.00 standby costs through automatic scale-to-zero and the Always Free tier, establishing a comprehensive automation toolkit alongside autonomous Gemini Managed Agents.

Getting Started and Repository

For comprehensive step-by-step setup guides, prerequisite configurations, one-click deployment procedures, and troubleshooting instructions, please refer to the complete documentation in the GitHub repository:

Detailed Usage Guide & Repository: https://github.com/tanaikech/cloud-run-sandbox-gas
One-Click Deployment Script: cloud_run/deploy.sh
FastAPI Proxy Runner: cloud_run/main.py
Google Apps Script Orchestrator: gas/Code.js
GAS Test Suite Definitions: gas/TestCases.js
Complete Resource Cleanup Script: scripts/cleanup.sh

Bidirectional Writeback for Apache Iceberg via Google Sheets: Serverless Lakehouse Console

Tanaike — Tue, 08 Sep 2026 06:41:28 +0000

Turn Google Sheets into a Fully Interactive, Differential ACID Mutation Console for Apache Iceberg without Reverse ETL SaaS or Cloud Servers.

Hero Infographic: Interactive Bidirectional Lakehouse Writeback via Google Sheets & Apache Iceberg. Enables business operators to query filtered records from an open Apache Iceberg table on Google Cloud Storage, visually edit values, add new rows, or purge obsolete records directly within a Google Sheets grid with an embedded dark-themed console, and commit atomic, microsecond-tolerant ACID mutations back to Parquet storage via BigQuery without Reverse ETL SaaS or persistent servers.

Structural Analysis of the Hero Infographic:

The hero infographic illustrates the complete, self-contained operational loop connecting frontline spreadsheet agility with immutable open lakehouse storage across three interconnected stages:

1. Predicate Query (Apache Iceberg Open Lakehouse on GCS): The left section shows the enterprise analytical foundation hosted on Google Cloud Storage, where Apache Iceberg manages immutable Parquet data files, hierarchical Avro metadata, and commit snapshots. When a user requests high-value records, BigQuery acts as an on-demand distributed compute accelerator, executing SQL queries with predicate pushdown (e.g., SELECT * WHERE price > 1000 ORDER BY id ASC) to fetch precise subsets in sub-seconds.
2. Frontline Editing in Google Sheets (Intuitive Operational Experience): The central section features a modern, user-friendly Google Sheets grid docked with the sleek dark-themed Iceberg Lakehouse Console sidebar. A business user effortlessly modifies data on the grid with immediate visual feedback: modifying existing values (e.g., updating price from 1500 to 123), appending new rows with unique primary keys (+ ADD (New Row id:121)), and deleting obsolete rows (🗑️ DELETE (Removed id:104)). Native cell validation guarantees data cleanliness, while a Privacy Mode toggle ([🔒 Privacy: ON]) automatically masks sensitive project identifiers during live broadcasting and screencasting.
3. Atomic ACID Writeback (Google Apps Script CDC & MERGE INTO): The right section highlights the serverless Change Data Capture (CDC) engine operating entirely in Google Apps Script. It detects diffs against an immutable hidden baseline and synthesizes a single atomic MERGE INTO SQL statement equipped with Optimistic Concurrency Control (OCC) and microsecond-discrepancy tolerance (TIMESTAMP_DIFF). BigQuery commits the transaction back to the Iceberg table in sub-seconds, generating fresh Parquet snapshots with zero third-party SaaS subscription fees ($0/month) and zero data egress risk.

Abstract

In our previously published foundational article, Unifying Google Workspace and Apache Iceberg: Serverless Lakehouse Management, we demonstrated how the open-source IcebergApp library overcomes Google Sheets' 10-million cell limit and script timeouts by offloading petabyte-scale analytical queries to BigQuery-accelerated Apache Iceberg storage. While that work established high-throughput read access and metadata pruning, enterprise frontline workflows require a complete operational loop: the ability to persist frontline spreadsheet edits, row additions, and deletions back to the analytical lakehouse.

Commercial Reverse ETL SaaS platforms bridge this writeback gap only at the cost of steep recurring subscriptions ($1,500–$5,000/month), third-party data egress risks, and high operational complexity. This article introduces a 100% serverless, zero-maintenance bidirectional writeback architecture built upon IcebergApp and Google Apps Script (GAS). Note that while the underlying IcebergApp library natively supports arbitrary binary data (BYTES), this writeback architecture and test suite operate on Google Sheets and are specifically designed for structured tabular text and numerical data. By coupling an in-memory Change Data Capture (CDC) engine with BigQuery’s distributed compute accelerator, this system empowers end users to interactively query, validate, edit, and commit differential mutations directly to open Apache Iceberg tables on Google Cloud Storage. The architecture features an atomic single-query MERGE INTO SQL synthesis with explicit type casting and Optimistic Concurrency Control (OCC) equipped with microsecond-discrepancy tolerance (TIMESTAMP_DIFF), a Privacy Mode toggle for screencasts and video demonstrations, deterministic primary-key sorting (ORDER BY id ASC), a 100,000-cell browser safety guard, an interactive dark-themed sidebar console with dynamic execution badges and in-app guidance, a fully autonomous headless test suite guaranteeing zero-residue lifecycle cleanup, and an unedited 77-second end-to-end video demonstration showcasing the complete 10-step operational lifecycle.

1. Introduction: The Operational Gap in Modern Lakehouses

Modern enterprise analytical architectures have standardized on open table formats, with Apache Iceberg emerging as the dominant standard across Google Cloud, AWS, and modern data stacks. By decoupling physical Parquet storage on Google Cloud Storage (GCS) from compute engines, Apache Iceberg provides ACID transactions, partition evolution, snapshot isolation, and sub-second Predicate Pushdown.

Yet, a critical disconnect persists on the enterprise frontlines: business operators live in spreadsheets, while analytical data lives in lakehouses.

Figure 1: The Enterprise Reality Gap: Frontline Spreadsheets vs. Modern Lakehouse. Illustrates the operational chasm between agile frontline business tasks in Google Workspace and immutable analytical storage in Apache Iceberg on Google Cloud, bridged seamlessly by IcebergApp's serverless bidirectional writeback engine.

Architectural Narrative for Figure 1:

As illustrated in Figure 1, the modern enterprise data landscape is sharply divided into two disconnected environments:

Left Panel (Frontline Operational Workflows): Business users work dynamically within Google Workspace (Google Sheets), performing daily operational adjustments such as master data corrections, price and discount overrides, IoT telemetry calibration offsets, and data anomaly removals. These operations require immediate visual feedback and frictionless spreadsheet manipulation.
Right Panel (Enterprise Analytical Storage): Core analytical assets reside in Google Cloud Storage as Apache Iceberg tables composed of immutable Parquet data files, hierarchical Avro manifest trees, and snapshot commit logs managed by BigQuery's distributed MPP query engine.
The Central Chasm & The IcebergApp Bridge: Between these two worlds stands an operational disconnect. Traditional tools like Google Connected Sheets provide only a unidirectional, read-only window, while third-party Reverse ETL SaaS platforms impose severe cost penalties ($1,500–$5,000/month) and enterprise compliance egress risks. IcebergApp functions as the vital serverless bidirectional bridge, enabling frontline operators to commit verified, sub-second ACID mutations directly to Parquet storage without intermediate SaaS platforms or persistent server infrastructure.

Consider common frontline operations: a pricing manager adjusts discount thresholds based on supply chain volatility; an operations engineer enters calibration offsets for industrial IoT sensors; or a master data steward flags and deletes corrupted duplicate records. In every modern organization, these decisions occur visually within Google Sheets.

1.1 The Connected Sheets Wall: The Unidirectional Bottleneck

Google Cloud addressed petabyte-scale spreadsheet querying by introducing Google Connected Sheets. Connected Sheets connects spreadsheets directly to BigQuery, enabling non-technical users to build pivot tables, charts, and formulas over billions of rows without writing SQL.

However, Connected Sheets is strictly unidirectional (Read-Only). If a business operator identifies a mispriced SKU, corrects an inaccurate telemetry reading, or deletes an invalid row in the spreadsheet grid, Connected Sheets offers no native pathway to write those mutations back to BigQuery or the underlying Apache Iceberg catalog. The user is forced to request data engineering tickets, manually export CSV files, or rely on ad-hoc scripts.

1.2 The SaaS Reverse ETL Tax & Compliance Egress

To solve this writeback dilemma, enterprises frequently turn to commercial Reverse ETL platforms (e.g., Census, Hightouch, Coefficient). While functional, these platforms introduce severe architectural drawbacks:

Extravagant Subscription Overhead: Enterprise Reverse ETL platforms typically cost between $1,500 and $5,000 per month, introducing substantial recurring operational expenditure for what is fundamentally periodic tabular synchronization.
Data Sovereignty & Compliance Egress: Synchronizing data via third-party SaaS vendors requires granting external platforms read and write access to internal datasets, transmitting confidential enterprise records outside the Google Cloud Virtual Private Cloud (VPC) and violating strict regulatory frameworks (GDPR, HIPAA, SOC2).
Lakehouse Metadata Ignorance: Most Reverse ETL tools operate at the generic SQL table layer and lack native understanding of Apache Iceberg metadata, triggering frequent small-file updates, manifest fragmentation, and uncoordinated snapshot generation.

1.3 The Solution: Serverless Bidirectional Lakehouse Writeback

Building directly upon the foundational IcebergApp engine established in our published companion article (Unifying Google Workspace and Apache Iceberg: Serverless Lakehouse Management), this work presents an end-to-end, container-bound Google Sheets application (applications/writeback-sheets-ui). Operating entirely within the Google Cloud and Google Workspace ecosystem, this architecture delivers:

Zero-Infrastructure Cost: Runs 100% serverlessly inside Google Apps Script (GAS) and BigQuery on-demand compute; $0 in monthly SaaS subscription fees.
Strict Data Sovereignty: All data remains strictly within customer-owned BigQuery datasets and Google Cloud Storage buckets. Zero third-party data egress.
Differential Change Data Capture (CDC): Accurately isolates ADDED, MODIFIED, and DELETED records by comparing the active spreadsheet grid against an immutable hidden baseline, with floating-point numeric tolerance to eliminate false diffs.
Atomic Single-Query MERGE INTO: Consolidates all mutations into a single optimized BigQuery MERGE INTO statement with explicit type casting and Optimistic Concurrency Control (OCC).
OCC with Microsecond Discrepancy Tolerance: Evaluates second-level delta assertions (TIMESTAMP_DIFF(T.updated_at, S._orig_updated_at, SECOND) = 0) to seamlessly bridge the microsecond precision disparity between BigQuery ($10^{-6}$s) and Google Sheets ($10^{-3}$s) while strictly intercepting concurrent background overwrites.
Privacy Mode for Video & Public Demonstrations: One-click DOM masking toggle ([🛡️ Privacy: OFF] ⇄ [🔒 Privacy: ON]) to mask sensitive GCP Project IDs, Dataset IDs, Bucket URIs, and queries with bullets (••••••••••••), enabling confidential screencasting while maintaining 100% backend execution fidelity.
Deterministic Primary-Key Ordering: Guarantees ascending primary-key sort order (ORDER BY id ASC) across both predicate pushdown queries and post-commit inspections.
Dual Operational Modes: A polished, dark-themed interactive console (Sidebar.html) featuring dynamic step badges, inline results, and in-app guidance for business operators, alongside an autonomous headless test suite (HeadlessTest.js) for CI/CD and engineering automation.
Text & Tabular Data Specification: While the core IcebergApp library natively supports arbitrary binary payloads (BYTES for PDFs, images, audio, and vector embeddings as explored in Article 2), this writeback architecture and test suite are specifically designed around the tabular grid characteristics of Google Sheets, focusing on structured text, numerical, and timestamp data only.

2. Technical Architecture & Component Interaction

Figure 2: End-to-end technical architecture of the Google Sheets to Apache Iceberg bidirectional writeback system. Displays the Google Sheets presentation tier, Apps Script CDC engine, BigQuery SQL accelerator, and Google Cloud Storage open lakehouse tier.

As visualized in Figure 2, the architecture cleanly decouples the spreadsheet presentation layer from serverless compute and open lakehouse storage across four synchronized tiers:

Architectural Narrative for Figure 2:

Figure 2 details the multi-tier operational coordination between Google Workspace and Google Cloud:

Tier 1: Presentation Tier (Google Sheets Ecosystem): Frontline users operate within standard Google Sheets tabs (queried_data, current_data) reinforced with native Data Validation rules. The interface is powered by Sidebar.html, rendering real-time execution badges, animated status spinners, an in-app editing guide, and an on-the-fly Privacy Mode toggle for secure screen broadcasting.
Tier 2: Orchestration & CDC Engine (Google Apps Script): Operating inside the serverless Apps Script V8 runtime, Code.js manages state transitions, tracks active edits against the hidden __iceberg_baseline__ sheet, applies floating-point tolerance filters, and synthesizes dynamic SQL payloads without requiring an intermediary backend server.
Tier 3: Distributed Compute Accelerator (BigQuery): BigQuery executes dynamic DDL/DML, interacts with the Iceberg REST Catalog, handles partition pruning, and atomically commits MERGE INTO operations with OCC timestamp assertions.
Tier 4: Open Lakehouse Storage (Google Cloud Storage): Apache Iceberg stores immutable columnar Parquet data files and Avro metadata trees directly in customer-controlled Cloud Storage buckets. Because data remains in open Iceberg format, external distributed engines (Apache Spark, Trino, DuckDB) can read and write concurrently without vendor lock-in.

2.1 Component Breakdown

Google Sheets Presentation Layer (Sidebar.html & Sheets Ecosystem):
- Custom Toolbar Menu: [Iceberg Lakehouse] -> [Open Lakehouse Console] provides immediate discovery.
- Modern Dark-Themed Sidebar UI: Styled with deep slate tones (#0f172a, #1e293b) and cyber-blue accents (#38bdf8), rendering real-time step lifecycle badges (PENDING, RUNNING, COMPLETED, FAILED), inline execution summaries, interactive cards, animated spinners, toast alerts, a one-click Privacy Mode toggle ([🛡️ Privacy: OFF] ⇄ [🔒 Privacy: ON]), an interactive in-app test guidance modal, and direct hyperlinks to the upstream GitHub repository.
- Tabular Sheets:
  - default_data: Staging area for initial sample records (5 columns $\times$ 20 rows).
  - queried_data: Active working sheet populated with query results and reinforced with native Google Sheets Data Validation rules.
  - current_data: Full lakehouse inspection sheet guarded by a 100,000-cell boundary limit and deterministically sorted by primary key (id ASC).
  - __iceberg_baseline__: Hidden, protected sheet holding the exact, immutable ground-truth snapshot of the most recent query.
Google Apps Script Change Data Capture (CDC) Engine (Code.js):
- Dynamic header-to-schema resolution, providing resilience against column reordering in the sheet.
- In-memory primary key (id) index comparison between active cells and baseline cells.
- Floating-point numeric tolerance ($< 10^{-9}$) to eliminate false diffs caused by display formatting.
- Synthesis of atomic BigQuery MERGE INTO SQL with explicit casting (CAST(val AS TYPE)) and string sanitization.
- Optimistic Concurrency Control (OCC) assertions checking row-level timestamps via TIMESTAMP_DIFF(T.updated_at, S._orig_updated_at, SECOND) = 0 to prevent microsecond roundoff conflicts.
BigQuery Lakehouse Compute Accelerator:
- Executes dynamic DDL (CREATE OR REPLACE TABLE) and DML (MERGE INTO).
- Serves as the distributed query engine that interfaces with the Iceberg REST Catalog, evaluating partition specifications and metadata pruning.
Apache Iceberg Open Lakehouse (Google Cloud Storage):
- Houses open Apache Parquet data files and Avro metadata manifests (*.metadata.json, *.avro).
- Maintains transactional snapshot history, enabling point-in-time Time Travel and multi-engine concurrent queries via Spark, Trino, and BigQuery without vendor lock-in.

3. The Algorithmic Core: Differential CDC & Atomic `MERGE INTO`

The core innovation of this writeback engine is the transformation of visual spreadsheet cell edits into a single, ACID-compliant database commit.

Figure 3: Algorithmic workflow of the Differential CDC Engine and Atomic MERGE INTO synthesis. Compares active sheet rows against the hidden baseline snapshot and generates an atomic BigQuery SQL query with explicit casting and OCC timestamp validation.

Algorithmic Narrative for Figure 3:

Figure 3 illustrates the five-phase algorithmic lifecycle that transforms frontline visual spreadsheet edits into an atomic, ACID-compliant database commit:

Phase 1 (Baseline Snapshotting): When rows are queried from the lakehouse via IcebergApp.getValues(), the active working dataset is populated into queried_data, and an exact, immutable clone is captured in the hidden __iceberg_baseline__ sheet, locked against user edits.
Phase 2 (Frontline Visual Manipulation): The business operator modifies existing cells, appends new rows with unique IDs, or deletes obsolete rows directly in the spreadsheet grid.
Phase 3 (In-Memory CDC Diffing): Clicking "Commit Changes (Writeback)" triggers the CDC engine, which indexes baseline and active rows by primary key (id), compares column hashes with numeric floating-point tolerance ($< 10^{-9}$), and partitions mutations into ADDED, MODIFIED, and DELETED sets.
Phase 4 (Atomic Single-Query MERGE INTO Synthesis): Rather than dispatching separate HTTP requests for each mutated row—which would cause timeouts and manifest fragmentation—the engine serializes all mutation sets into a single BigQuery MERGE INTO statement with an in-memory UNION ALL source table, explicit SQL type casting, and second-level OCC timestamp matching (TIMESTAMP_DIFF(T.updated_at, S._orig_updated_at, SECOND) = 0).
Phase 5 (ACID Commit & Baseline Synchronization): BigQuery executes the atomic transaction against Cloud Storage, updates Iceberg snapshot manifests, verifies that numDmlAffectedRows matches expected mutations, synchronizes __iceberg_baseline__ to the committed state, and alerts the operator via a success badge.

3.1 The Baseline Snapshot Strategy

When an operator queries the lakehouse (e.g., via stepExecuteQuery), the returned 2D array is rendered into queried_data. Simultaneously, an identical clone is written into __iceberg_baseline__.

This baseline sheet is:

Marked with Google Sheets protection to prevent accidental edits.
Programmatically hidden from the workbook tab bar (baselineSheet.hideSheet()).
Treated as the immutable ground-truth state against which all subsequent edits are measured.

3.2 In-Memory CDC Differentiation Algorithm

When the operator clicks "Commit Changes (Writeback)", the CDC engine in Code.js executes the following algorithm:

// Step 1: Index baseline rows by Primary Key (id)
const baselineMap = new Map();
for (let r = 1; r < baselineValues.length; r++) {
  const row = baselineValues[r];
  const pk = row[baselineIdIdx];
  if (pk !== null && pk !== "") {
    baselineMap.set(String(pk), rowToRecord_(row, baselineHeaders));
  }
}

// Step 2: Scan active sheet for Added and Modified rows
const addedRows = [];
const modifiedRows = [];
const activePkSet = new Set();
const nowIso = new Date().toISOString();

for (let r = 1; r < activeValues.length; r++) {
  const row = activeValues[r];
  const pk = row[activeIdIdx];
  if (!pk) continue;
  const pkStr = String(pk);
  activePkSet.add(pkStr);

  const activeRecord = rowToRecord_(row, activeHeaders);

  if (!baselineMap.has(pkStr)) {
    // ADDED Set: PK exists in active sheet, but absent in baseline
    activeRecord.updated_at = activeRecord.updated_at || nowIso;
    addedRows.push(activeRecord);
  } else {
    // MODIFIED Set: PK exists in both; verify column-level value hash
    const baseRecord = baselineMap.get(pkStr);
    if (isRecordModified_(activeRecord, baseRecord)) {
      activeRecord._orig_updated_at = baseRecord.updated_at; // Capture for OCC
      activeRecord.updated_at = nowIso; // New commit timestamp
      modifiedRows.push(activeRecord);
    }
  }
}

// Step 3: Scan baseline for Deleted rows
const deletedRows = [];
for (let [pkStr, baseRecord] of baselineMap.entries()) {
  if (!activePkSet.has(pkStr)) {
    // DELETED Set: PK exists in baseline, but absent in active sheet
    baseRecord._orig_updated_at = baseRecord.updated_at;
    deletedRows.push(baseRecord);
  }
}

3.3 Atomic `MERGE INTO` SQL Synthesis

Rather than executing individual INSERT, UPDATE, and DELETE statements across multiple network roundtrips—which would cause Google Apps Script timeouts and create dozens of fragmented Parquet commit files—the engine consolidates all mutations into a single, atomic BigQuery MERGE INTO query.

Every record across the Added, Modified, and Deleted sets is serialized into an in-memory UNION ALL source table constructor with explicit SQL type casting:

MERGE INTO `my-project.my_dataset.products` AS T
USING (
  -- ADDED RECORD: INSERT
  SELECT
    CAST(121 AS INT64) AS id,
    CAST('Quantum Frequency Comb' AS STRING) AS product,
    CAST(6200.0 AS FLOAT64) AS price,
    CAST(5 AS INT64) AS stock,
    TIMESTAMP '2026-09-07T06:15:00.000Z' AS updated_at,
    'INSERT' AS _action,
    TIMESTAMP '1970-01-01T00:00:00Z' AS _orig_updated_at
  UNION ALL
  -- MODIFIED RECORD: UPDATE
  SELECT
    CAST(105 AS INT64) AS id,
    CAST('Photonic Switch Array' AS STRING) AS product,
    CAST(2550.0 AS FLOAT64) AS price,
    CAST(8 AS INT64) AS stock,
    TIMESTAMP '2026-09-07T06:15:00.000Z' AS updated_at,
    'UPDATE' AS _action,
    TIMESTAMP '2026-09-07T00:00:00.000Z' AS _orig_updated_at
  UNION ALL
  -- DELETED RECORD: DELETE
  SELECT
    CAST(110 AS INT64) AS id,
    CAST(NULL AS STRING) AS product,
    CAST(NULL AS FLOAT64) AS price,
    CAST(NULL AS INT64) AS stock,
    TIMESTAMP '1970-01-01T00:00:00Z' AS updated_at,
    'DELETE' AS _action,
    TIMESTAMP '2026-09-07T00:00:00.000Z' AS _orig_updated_at
) AS S
ON T.id = S.id
-- 1. UPDATE MATCHED ROW WITH OCC TIMESTAMP GUARD (SECOND-LEVEL TOLERANCE)
WHEN MATCHED AND S._action = 'UPDATE' AND (TIMESTAMP_DIFF(T.updated_at, S._orig_updated_at, SECOND) = 0 OR S._orig_updated_at IS NULL) THEN
  UPDATE SET T.product = S.product, T.price = S.price, T.stock = S.stock, T.updated_at = S.updated_at
-- 2. DELETE MATCHED ROW WITH OCC TIMESTAMP GUARD (SECOND-LEVEL TOLERANCE)
WHEN MATCHED AND S._action = 'DELETE' AND (TIMESTAMP_DIFF(T.updated_at, S._orig_updated_at, SECOND) = 0 OR S._orig_updated_at IS NULL) THEN
  DELETE
-- 3. INSERT UNMATCHED NEW ROW
WHEN NOT MATCHED AND S._action = 'INSERT' THEN
  INSERT (id, product, price, stock, updated_at)
  VALUES (S.id, S.product, S.price, S.stock, S.updated_at);

3.4 Optimistic Concurrency Control (OCC) Protection & Microsecond Precision Tolerance

In enterprise environments, multiple automated ETL pipelines, IoT streaming jobs, or peer users may modify the same lakehouse table concurrently. To prevent the classic "lost update" anomaly, the MERGE INTO statement incorporates Optimistic Concurrency Control (OCC):

When an active row is modified or deleted, its original timestamp (_orig_updated_at) captured during query time is injected into the WHEN MATCHED clause.
The Microsecond Discrepancy Challenge: BigQuery stores TIMESTAMP values with microsecond precision ($10^{-6}$s) and returns them via its REST API as floating-point epoch seconds (e.g., "1700000000.123456"). Conversely, Google Sheets and standard JavaScript Date objects operate at millisecond precision ($10^{-3}$s). A naive strict equality comparison (T.updated_at = S._orig_updated_at) invariably causes false concurrency conflicts even on completely untouched rows due to sub-millisecond truncation and floating-point roundoff.
Resolution via TIMESTAMP_DIFF: The OCC condition enforces second-level equality: TIMESTAMP_DIFF(T.updated_at, S._orig_updated_at, SECOND) = 0 Coupled with automatic ISO 8601 normalization in IcebergApp.js and flexible epoch parsing in Code.js, this provides ironclad concurrency protection against actual external updates while completely eliminating false collision errors.
If an external process modifies that row between query and writeback, TIMESTAMP_DIFF evaluates to non-zero. The row mutation is skipped, causing BigQuery's reported numDmlAffectedRows to fall below the expected count (added.length + modified.length + deleted.length).
The script immediately intercepts this discrepancy and throws an actionable Concurrency Conflict exception, preserving database integrity.

4. Interactive UI Walkthrough: The 10-Step Operational Lifecycle

Figure 4: The 10-Step Operational Lifecycle: Interactive Lakehouse Writeback in Google Sheets. Illustrates the end-to-end operational journey across 10 progressive phases from container-bound script binding to zero-residue cloud teardown.

Operational Narrative for Figure 4:

As visualized in the 10-step workflow of Figure 4, the system orchestrates a structured, self-guided operational journey arranged across two interconnected rows of five progressive phases:

Phase 1: Environment Setup & Interface Initialization (Steps 1–3):
- Step 1 (Script Binding & Setup): Developers bind the foundational IcebergApp.js library, application backend Code.js, frontend Sidebar.html, and HeadlessTest.js into the Google Spreadsheet container, enabling the BigQuery v2 Advanced Service in appsscript.json.
- Step 2 (Custom Menu & GCP Config): The spreadsheet initializes a top toolbar menu [Iceberg Lakehouse] -> [Open Lakehouse Console] and prompts the operator for GCP Project ID and Region, securely caching them in UserProperties.
- Step 3 (Sidebar Console & Privacy Mode): The modern dark console launches in the right sidebar, offering dynamic lifecycle badges (PENDING, RUNNING, COMPLETED, FAILED) and a one-click Privacy Mode toggle ([🛡️ Privacy: OFF] ⇄ [🔒 Privacy: ON]) for confidential video broadcasting.
Phase 2: Cloud Infrastructure & Table Provisioning (Steps 4–5):
- Step 4 (Infrastructure Provisioning): Automated background routines provision an isolated BigQuery dataset and Cloud Storage bucket, while staging 20 sample product records into default_data.
- Step 5 (Iceberg Table Creation): IcebergApp.create() synthesizes the Iceberg table with DATE(updated_at) partitioning and id clustering, streaming initial records into Parquet storage.
Phase 3: Predicate Pushdown & Frontline Manipulation (Steps 6–7):
- Step 6 (Query & Sheet Validation): Executes filtered lakehouse queries with predicate pushdown into queried_data, injects native Google Sheets Data Validation rules, clones an immutable baseline snapshot into __iceberg_baseline__, and launches an in-app test guidance modal.
- Step 7 (Visual In-Sheet Editing): Business users modify prices or stock, append new rows with unique primary keys in column A, or delete obsolete rows directly on the spreadsheet grid.
Phase 4: ACID Commit, Full Audit & Zero-Residue Purge (Steps 8–10):
- Step 8 (Differential Writeback Commit): The CDC engine computes diffs, synthesizes a single atomic MERGE INTO SQL query with microsecond-tolerant OCC (TIMESTAMP_DIFF), and executes sub-second commit to BigQuery.
- Step 9 (Full Inspection & 100k Safeguard): Evaluates dataset volume against the 100,000-cell browser safety limit and exports all lakehouse rows to current_data sorted deterministically by primary key (id ASC).
- Step 10 (Clean Reset & Zero-Residue Purge): Drops the Iceberg table, purges GCS bucket objects, deletes the bucket and dataset, and clears spreadsheet tabs while preserving GCP project configuration for instant re-testing.

Live Demonstration Video: The Complete 10-Step Lifecycle in Action (77s)

The following screencast video demonstration captures the entire unedited operational lifecycle (77 seconds) directly within Google Sheets and the right-docked "Iceberg Lakehouse Console" sidebar—from infrastructure initialization, Iceberg table provisioning, and predicate pushdown querying, to frontline grid modifications (in-place edits and row deletions), differential CDC commit via atomic MERGE INTO, full data inspection, and zero-residue environment teardown.

Live Demonstration Video: End-to-end execution of the interactive Apache Iceberg bidirectional writeback console in Google Sheets (77s). ▶️ Open raw video file (demo.mp4)

Video Timeline & Operational Highlights:

Timestamp	Operational Phase & Action	On-Screen Behavior & Backend Execution
0:00 - 0:10	Step 1: Setup & Staging	Privacy Mode ON (automatically masking GCP Project IDs and Dataset names as `••••••••••`). The user clicks `Initialize Infrastructure`, provisioning an ephemeral BigQuery dataset and GCS bucket, and staging 20 sample rows into `default_data`.
0:10 - 0:20	Step 2: Table Creation	The user clicks `Create Iceberg Table`. `IcebergApp.create()` generates the Apache Iceberg table on GCS and commits the initial 20 rows in Parquet format. The sidebar query textarea is pre-populated with a filtered query.
0:20 - 0:32	Step 3: Query & Validate	The user executes the query (`WHERE price > 1000.0 ORDER BY id ASC`). Predicate pushdown loads matching records into `queried_data`, injects native column validation rules (positive numbers, integers), and clones the baseline.
0:32 - 0:48	Frontline Grid Manipulation	Direct editing on `queried_data`: • Row 2 (`id: 101`): Updates product name to `Sample 1` and price to `123`. • Row 3 (`id: 103`): Updates product name to `Sample 2` and price to `456`. • Row 4 (`id: 104`): Right-clicks and selects "Delete row", removing `Superconducting Resonator`.
0:48 - 0:55	Step 4: Differential Writeback	The user clicks `Commit Changes (Writeback)`. In-memory CDC detects diffs instantly and synthesizes a single `MERGE INTO` SQL statement with microsecond OCC, committing it to BigQuery. Badge: `✅ Done: Committed: 0 added, 2 modified, 1 deleted (Affected: 3 rows)`.
0:55 - 1:08	Step 5: Full Inspection	The user clicks `Get All Current Data` (enforcing the 100k-cell safety guard). Exports all lakehouse rows to `current_data` sorted deterministically by primary key (`ORDER BY id ASC`). Confirms `id: 101` and `103` are updated, `104` is purged, and `102` & `105`+ are intact.
1:08 - 1:17	Step 6: Reset & Teardown	The user clicks `All Reset & Purge` (Danger zone). Drops the Iceberg table, deletes all GCS objects and bucket, removes the BigQuery dataset, and clears working tabs—restoring the pristine initial state with zero leftover cloud residue.

The application provides a seamless, self-guided experience directly inside Google Sheets, illustrated in Figure 4 and demonstrated in the live screencast:

Step 1: Container-Bound Script Setup

The core library (src/IcebergApp.js) and application code files (Code.js, Sidebar.html, HeadlessTest.js) are bound directly to the active spreadsheet via Extensions > Apps Script (or linked as a library), with the BigQuery v2 Advanced Service enabled in appsscript.json. Incorporating src/IcebergApp.js as the foundational engine is a mandatory prerequisite that provides full-featured Iceberg DDL, metadata-driven predicate pushdown, and transactional table operations.

Step 2: Custom Menu & GCP Initialization

Upon opening the spreadsheet, the onOpen() hook registers the top menu: [Iceberg Lakehouse] -> [Open Lakehouse Console]. If GCP properties are not yet set, an input dialog prompts the operator for their GCP Project ID and Region (defaulting to asia-northeast1), storing them securely in PropertiesService.getUserProperties().

Step 3: Modern Dark-Themed Sidebar Console & Privacy Mode

Opening the console displays Sidebar.html in the right dock. The interface features a status panel showing active GCP parameters, real-time connection badges, a one-click Privacy Mode toggle ([🛡️ Privacy: OFF] ⇄ [🔒 Privacy: ON]) to mask sensitive project IDs and SQL queries for video recording, hyperlinks to the upstream GitHub repository, and sequentially numbered action cards with dynamic lifecycle badges (PENDING, RUNNING, COMPLETED, FAILED). (The embedded screencast demo clearly showcases Privacy Mode enabled throughout execution, ensuring sensitive GCP Project IDs and Dataset names are masked as •••••••••• without impacting backend execution.)

Step 4: Infrastructure Provisioning & `default_data` Staging

Clicking "Initialize Infrastructure" triggers:

ensureBigQueryDataset_: Creates an isolated BigQuery dataset lakehouse_writeback_[timestamp].
ensureGcsBucket_: Creates an isolated Cloud Storage bucket gs://lakehouse-iceberg-wb-[project]-[timestamp] with Uniform Bucket-Level Access.
stageDefaultData_: Creates a clean sheet named default_data and populates 20 realistic enterprise product records (headers: id, product, price, stock, updated_at).
The Step 1 card updates with a green COMPLETED badge and inline details of the provisioned resources.

Step 5: Iceberg Table Provisioning

Clicking "Create Iceberg Table" invokes IcebergApp.create(), defining the table schema, setting the Cloud Storage URI, configuring DATE(updated_at) partitioning, and setting id clustering. The 20 staged rows are inserted via table.insertValues(), the Step 2 card displays a green COMPLETED badge showing the created table name and ingested row count, and the sidebar query textarea is automatically populated with:

SELECT * FROM `project.dataset.products` WHERE price > 1000.0 ORDER BY id ASC

Step 6: Query Execution & In-Sheet Data Validation Injection

Clicking "Execute Query" runs the query with Predicate Pushdown. The results are written to queried_data. Simultaneously, the engine injects native Google Sheets Data Validation rules:

price: Locks inputs to positive numbers ($> 0$).
stock: Locks inputs to non-negative integers ($\ge 0$).
id: Restricts inputs to valid positive integer IDs. An exact replica is copied to the hidden, protected sheet __iceberg_baseline__. Interactive In-App Guidance: Upon query completion, an informative modal dialog automatically appears explaining how to test differential edits (Modify, Delete, Add) in queried_data. Users click "Got it! Close & Start Editing" to immediately begin testing, with a persistent [View Guide] button available in the card for subsequent reference.

Step 7: Visual In-Sheet Manipulation

The business operator performs standard spreadsheet edits in queried_data:

Modify: Edits price or stock in place (e.g., updates id=105 price to 2550.0).
Add: Appends a new row at the bottom with a unique ID in column A (e.g., id=121, "Quantum Frequency Comb", price=6200.0, stock=5). Note that primary key id is strictly mandatory.
Delete: Right-clicks and deletes an obsolete row (e.g., deletes id=110).

Step 8: Differential Writeback Commit

Clicking "Commit Changes (Writeback)" triggers the CDC engine. The diff is calculated, the single atomic MERGE INTO SQL is synthesized with second-level timestamp tolerance (TIMESTAMP_DIFF(..., SECOND) = 0) and floating-point tolerance ($10^{-9}$), BigQuery executes the transaction, numDmlAffectedRows is verified, and __iceberg_baseline__ is updated. A green toast and inline summary confirm:
"Committed successfully: 1 added, 1 updated, 1 deleted (Total DML affected rows: 3)."

Step 9: Full Data Inspection & 100,000-Cell Safeguard

Clicking "Get All Current Data" runs a pre-flight row count check. If total_rows * columnCount > 100,000, the operation aborts with an alert to prevent browser memory saturation. Otherwise, all rows are exported to current_data via table.exportToSheet() with { orderBy: "id ASC" } and sorted by ID ascending at the sheet level, guaranteeing deterministic primary key ordering for visual audit of the lakehouse state.

Step 10: All Reset & Zero-Residue Purge

Clicking "All Reset & Purge" displays a confirmation dialog. Upon approval, the engine drops the Iceberg table, deletes all objects in the GCS bucket, removes the bucket, drops the BigQuery dataset, and purges spreadsheet tabs. Crucially, the engine preserves ICEBERG_PROJECT_ID and ICEBERG_REGION in UserProperties, allowing immediate frictionless re-testing from Step 1 while guaranteeing 100% zero leftover cloud storage or table resources.

5. Comparative Benchmark: IcebergApp vs. Reverse ETL SaaS vs. Connected Sheets

Figure 5: Architectural, cost, and security comparison between IcebergApp Writeback Engine, Commercial Reverse ETL SaaS platforms, and Google Connected Sheets across four critical dimensions.

Comparative Narrative for Figure 5:

Figure 5 evaluates the three competing architectural paradigms across four critical operational dimensions:

Dimension 1: Total Cost of Ownership (TCO): Commercial Reverse ETL SaaS platforms impose recurring subscription commitments ranging from $1,500 to $5,000 per month based on sync frequency and sync row volume. In contrast, Google Connected Sheets and the IcebergApp Writeback Engine incur $0 in monthly licensing fees, operating on serverless, pay-per-query BigQuery compute.
Dimension 2: Synchronization Directionality & Latency: Connected Sheets remains strictly unidirectional (read-only), offering zero writeback capability. Commercial Reverse ETL tools operate via scheduled micro-batches that introduce 5-minute to 1-hour delays. The IcebergApp Writeback Engine delivers sub-second, interactive bidirectional synchronization, committing frontline edits immediately via atomic MERGE INTO transactions.
Dimension 3: Data Sovereignty & Security Compliance: Commercial Reverse ETL forces confidential enterprise records across third-party SaaS infrastructure, creating significant egress vulnerabilities and complicating GDPR, HIPAA, and SOC2 compliance. Conversely, Connected Sheets and IcebergApp operate 100% within customer-owned Google Cloud tenants, guaranteeing that data never leaves the organizational boundary.
Dimension 4: Table Format & Multi-Engine Openness: Reverse ETL platforms typically synchronize into proprietary staging caches or basic relational tables. IcebergApp commits mutations directly to open Apache Iceberg Parquet files and Avro manifest trees on Google Cloud Storage, allowing simultaneous, zero-copy querying by Apache Spark, Trino, Snowflake, and BigQuery without vendor lock-in.

To quantify the strategic advantages of this architecture, Figure 5 and the table below evaluate the three primary approaches to spreadsheet-lakehouse integration:

Evaluation Metric	Commercial Reverse ETL SaaS (Census, Hightouch)	Google Connected Sheets	IcebergApp Writeback Engine (This Work)
Monthly Infrastructure Cost	$1,500 – $5,000 / month (Tiered subscription + data volume)	$0 (Included with Google Workspace & GCP)	$0 (Serverless; on-demand BigQuery queries only)
Data Synchronization Direction	Bidirectional (via separate scheduled sync flows)	Strictly Unidirectional (Read-Only)	Fully Bidirectional (Interactive Read & Differential Writeback)
Transaction & Latency Profile	Scheduled micro-batches (5 min – 1 hour delay)	Scheduled queries or manual refresh	Sub-Second ACID Upsert (`MERGE INTO`)
Data Sovereignty & Security	Egress Risk: Data transmitted to 3rd-party SaaS infrastructure	100% GCP VPC: Data remains in BigQuery	100% GCP VPC: Pure direct BigQuery & GCS interaction
Storage & Table Format	Generic SQL tables (often proprietary data copies)	BigQuery Managed Tables	Open Apache Iceberg Parquet & Avro Manifests
Concurrency Protection	Basic batch overwrite or last-write-wins	N/A (Read-Only)	Optimistic Concurrency Control (OCC) with Timestamp Gates
Setup & Maintenance Overhead	High: External OAuth, webhooks, SaaS connectors	Low: Native UI feature	Zero: Single Google Sheets container-bound script

Why the Serverless Writeback Engine Wins

$0 Fixed TCO: Eliminates enterprise SaaS licensing fees entirely. An organization performing 100 daily writebacks spends less than $0.05 per month in BigQuery query fees.
Zero Vendor Lock-In: Because data is committed directly to Apache Iceberg format on Cloud Storage, external engines (Apache Spark, Trino, Snowflake) can immediately read committed data without re-exporting.
Ironclad Enterprise Security: Compliance officers do not need to review third-party vendor SOC2 reports or execute Data Processing Agreements (DPAs); all data stays strictly within the organization's GCP tenant.

6. Autonomous Headless Test Suite (`HeadlessTest.js`): The Primary Verification Gate

As a foundational best practice, the architecture implements a two-stage verification workflow: users execute the autonomous headless suite (HeadlessTest.js) first directly in the Apps Script editor. Running runAutonomousWritebackHeadlessTest() validates that GCP credentials, IAM roles, BigQuery Advanced Service, and the core IcebergApp.js engine operate flawlessly without any UI or spreadsheet interference. Once this primary gate passes cleanly, users proceed to the interactive Google Sheets UI console with full confidence.

6.1 Headless Execution Flow & Assertions

Operating completely in the Google Apps Script V8 runtime without opening Google Sheets or touching UI components, the test suite executes an 8-stage verification pipeline adhering to Protocol 17 (Note: While the core IcebergApp library natively supports binary BYTES payloads, this test suite is purpose-built to validate bidirectional interoperability with Google Sheets tabular grids, meaning its verification schema is strictly specified for structured text and numerical fields: id INT64, product STRING, price FLOAT64, stock INT64, updated_at TIMESTAMP):

Figure 6: Autonomous Headless Verification Pipeline: 8-Stage Quality Gate for Apache Iceberg and Google Apps Script. Illustrates the end-to-end headless quality gate across 8 sequential verification stages and final zero-residue teardown.

Operational Narrative for Figure 6:

As visualized in Figure 6, the headless verification engine orchestrates an automated 8-stage quality gate followed by guaranteed resource cleanup:

Stages 1–2 (Ephemeral Provisioning & DDL): Stage 1 provisions an isolated, timestamped BigQuery dataset and Cloud Storage bucket. Stage 2 executes IcebergApp.create() to generate the partitioned and clustered open Iceberg table.
Stages 3–4 (Ingestion & Predicate Pushdown): Stage 3 inserts 20 structured records (asserting insertedCount === 20). Stage 4 executes a filtered query with SQL predicate pushdown (price > 1000.0), asserting that exactly 15 records match.
Stages 5–6 (CDC Simulation & Atomic Mutation): Stage 5 simulates frontline spreadsheet modifications in memory (1 added, 1 modified, 1 deleted row). Stage 6 synthesizes and fires the atomic MERGE INTO SQL statement, asserting that numDmlAffectedRows === 3.
Stages 7–8 (OCC Integrity & Safety Guard): Stage 7 verifies post-commit row states and validates that stale timestamps are strictly rejected by Optimistic Concurrency Control. Stage 8 deliberately triggers the 100,000-cell boundary to assert that defensive memory guards prevent client crash.
FINALLY (Absolute Zero-Residue Teardown): Purges all Parquet data, drops the Iceberg table, and permanently removes the bucket and dataset, leaving zero lingering cloud resources.

6.2 Verifying the Zero-Residue Lifecycle

The finally block in HeadlessTest.js guarantees that even if an assertion fails midway through execution, all created cloud resources are completely eradicated:

finally {
  console.log("--- ABSOLUTE CLEANUP: Purging Ephemeral Headless Test Resources ---");
  if (table) {
    try { table.remove(true); } catch (e) { console.warn(e.message); }
  }
  if (datasetCreated) {
    try { BigQuery.Datasets.remove(projectId, testCatalogName, { deleteContents: true }); } catch (e) { console.warn(e.message); }
  }
  if (bucketCreated) {
    try { deleteGcsBucketCompletely_(testBucketName); } catch (e) { console.warn(e.message); }
  }
  console.log("✨ Headless cleanup complete. Zero residue.");
}

7. Security, Defensive Protocols & Best Practices

SQL Injection Immunity: All spreadsheet text cells are sanitized using strict string escape routines (escapeSqlString_), converting backslashes to \\\\ and single quotes to \\'. Numeric columns are strictly validated via Number.isFinite(), and empty numeric cells are cast safely to CAST(NULL AS FLOAT64).
BigQuery DML Error Interception: In compliance with Protocol 17, runBqJob_ polls BigQuery.Jobs.getQueryResults and inspects the errors array. Any syntax, quota, or permission errors are formatted into human-readable alerts rather than failing silently.
Data Validation Hard Boundaries: Attaching Google Sheets Data Validation rules directly to columns at query time prevents users from entering malformed data (such as entering negative stock or alphanumeric strings in price columns) before writeback dispatch.
100,000-Cell Memory Guard: Google Sheets tabs can become sluggish or crash browser tabs when rendering hundreds of thousands of cells. Pre-flight calculation of total_rows * column_count prevents uncontrolled full-table dumps.
Privacy Mode Credential Shielding: Client-side DOM masking allows operators to record tutorial videos or perform public demonstrations without revealing project IDs, dataset names, or storage paths. Dynamic in-memory unmasking ensures backend RPC execution remains 100% genuine and seamless.
Microsecond Timestamp & Float Tolerance: Precision normalization and second-level delta checks (TIMESTAMP_DIFF(..., SECOND) = 0) in SQL OCC prevent subtle millisecond-to-microsecond roundoff mismatches between Google Sheets and BigQuery from corrupting transactional integrity.

8. Conclusion & Future Horizons

The Apache Iceberg End-User Writeback UI demonstrates that Google Sheets and enterprise open lakehouses are not mutually exclusive. By pairing Google Apps Script with BigQuery as a distributed compute engine and Apache Iceberg on Google Cloud Storage, developers can construct responsive, secure, and bidirectional operational interfaces in minutes without paying recurring SaaS subscription fees.

Future Horizons & Extensions:

Multi-Table Relational Writebacks: Extending the CDC engine to support composite foreign key joins across multiple related sheets.
Gemini Agentic Governance: Integrating Google Workspace AI (Gemini) directly into the sidebar console to perform automated anomaly audits and explain CDC deltas in plain English before writeback execution.
Delta Lake & Hudi Federation: Adapting the single-query MERGE INTO synthesizer to support multi-format lakehouse engines simultaneously.

The complete code, sidebar templates, and headless test suites are open source and available in the IcebergApp repository.

References & Documentation

Serverless Multimodal Vector Search on Apache Iceberg via Google Apps Script

Tanaike — Tue, 08 Sep 2026 05:06:23 +0000

Turn Google Drive into an AI-Powered Lakehouse Vector Engine across Converted PDFs, Binary Images, and Text without Specialized Vector Databases.

Hero Infographic: Unified Multimodal Lakehouse Vector Search via Apache Iceberg & Google Apps Script. Consolidates Google Docs, Sheets, Slides, Forms, binary diagrams, and web-fetched assets into an open Parquet table, driven by Gemini embeddings and BigQuery serverless pushdown for sub-second semantic retrieval and live Google Drive discovery.

Structural Analysis of the Hero Infographic:

The hero infographic visualizes the end-to-end paradigm shift enabling unified multimodal storage and sub-second semantic discovery across three synchronized operational zones:

Left Zone (Diverse Multimodal Ingestion): Ingests heterogeneous corporate knowledge spanning Google Drive assets (Docs with automated PDF normalization, Sheets data/PDFs, Slides presentations, and Forms intake/response structures), binary media (PNG/JPEG schematics and diagrams), and web-crawled/HTTP-downloaded external files into a unified ingestion pipeline.
Center Zone (Serverless Processing & Unified Iceberg Lakehouse): The IcebergApp.js engine running purely within Google Apps Script extracts payloads and routes textual representations to the Gemini Embedding API (text-embedding-004) to synthesize 768-dimensional normalized float vectors (ARRAY<FLOAT64>). These are committed alongside raw binary streams (data BYTES), metadata, and authentic Google Drive identifiers (file_id STRING) into a Single Apache Iceberg Table hosted on Google Cloud Storage.
Right Zone (Serverless Query & Live File Discovery): When an operator issues a natural language query, BigQuery executes distributed COSINE_DISTANCE pushdown directly across the open Parquet files on Cloud Storage. Within 0.3 to 0.5 seconds, ranked results (with similarity metrics exceeding 0.87) are returned, enabling instant 1-click browser navigation back to the live collaborative document or triggering programmatic Workspace automation.

Abstract

Enterprise knowledge is notoriously fragmented across structured tabular records, raw text notes, binary diagrams, and rich documents stored in Google Drive. Traditional Retrieval-Augmented Generation (RAG) and semantic search architectures address this challenge by deploying dedicated vector database clusters (e.g., Pinecone, Milvus, Qdrant) or specialized Reverse ETL pipelines. However, these systems introduce steep subscription costs, operational complexity, and vendor lock-in, while isolating embeddings from core analytical storage.

This article introduces a 100% serverless, zero-maintenance Multimodal Lakehouse Vector Search architecture built on IcebergApp, Google Apps Script (GAS), and BigQuery. Leveraging Apache Iceberg's native support for binary data (BYTES), this system ingests heterogeneous assets—including live Google Docs automatically converted into PDF binary blobs, raw image diagrams, and direct plain text records—into an open Parquet table on Google Cloud Storage. Crucially, by persisting the authentic Google Drive file_id alongside the binary PDF snapshot, vector search results immediately map back to the live collaborative document (https://docs.google.com/document/d/${file_id}/edit), transforming Apache Iceberg into an enterprise-grade semantic file search engine for Google Workspace. Vector embeddings are generated on-the-fly using the Gemini API (text-embedding-004) and queried using distributed vector distance metrics (COSINE_DISTANCE) with sub-second latency. Furthermore, to enable developers to safely evaluate the pipeline within their own Google Cloud environment, the article includes an autonomous test suite equipped with an automated self-cleaning mechanism that guarantees zero-residue cleanup of temporary test assets, empowering Workspace developers to evaluate and deploy enterprise-grade multimodal search engines directly from Google Apps Script.

1. Introduction: The Fragmentation of Multimodal Knowledge

In modern enterprise operations, knowledge does not reside neatly in relational database rows. It lives in diverse multimodal formats scattered across Google Workspace and cloud storage:

Rich Documents: Standard operating procedures, technical manuals, and architectural specifications in Google Docs; financial models and analytical KPIs in Google Sheets; pitch decks and visual proposals in Google Slides; and questionnaire forms and intake responses in Google Forms.
Visual Artifacts: System architecture schematics, flowcharts, and infographics saved as PNG/JPEG images.
Direct Operational Text: Real-time event notes, error logs, and transactional summaries written directly in code or spreadsheets.

To visually capture this operational divide and contrast conventional, costly multi-tier architectures with our unified serverless design, Figure 1 outlines the structural evolution from isolated enterprise silos to an integrated Apache Iceberg lakehouse.

Figure 1: Fragmented Enterprise Data Silos & Traditional RAG vs. IcebergApp Unified Multimodal Serverless Lakehouse. Contrasts the high-cost, fragmented traditional RAG pipeline against the unified, zero-egress Apache Iceberg architecture powered by Google Apps Script and BigQuery on Google Cloud.

Detailed Architectural Analysis of Figure 1:

As clearly mapped in the comparative tiers of Figure 1, enterprise multimodal knowledge management undergoes a fundamental structural paradigm shift:

Top Section (Fragmented Enterprise Data Silos): In everyday operations, assets are created and stored in isolated systems: Google Docs, Sheets, Slides, and Forms inside Google Drive; PNG/JPEG diagrams residing in Cloud Storage or Drive; and operational event notes residing as raw text strings. Because these assets use incompatible storage primitives, traditional analytical systems cannot ingest or index them collectively.
Middle Section (Traditional Complex RAG Stack - The Problem): As depicted by the red-bordered warning flow in Figure 1, conventional architectures attempt to bridge these silos by introducing third-party Python microservices and dedicated vector databases (e.g., Pinecone, Milvus, Qdrant). This approach introduces three fatal operational penalties:
- Exorbitant Subscription Tax: Dedicated vector database clusters impose recurring fixed commitments between $500 and $3,000 per month, regardless of actual query volume.
- Severe Egress Vulnerabilities: Sensitive enterprise documents and intellectual property must leave the secure Google Cloud Virtual Private Cloud (VPC) and traverse external public networks to reach third-party SaaS platforms.
- Dual-Storage Synchronization Drift: Storing vector embeddings in a standalone vector database while keeping binary PDFs and images in separate object storage invariably leads to broken links, synchronization lags, and metadata drift.
Bottom Section (IcebergApp Unified Serverless Lakehouse - The Solution): Indicated by the glowing green and cyber-cyan borders in Figure 1, our architecture replaces this complex multi-tier stack with a clean, 100% serverless pipeline:
- Google Apps Script (V8 Engine): Directly interacts with Google Workspace APIs via DriveApp and native services, exporting Docs, Sheets, and Slides into standardized PDF binary blobs on-the-fly (and extracting Forms structure via FormApp or linked response sheets) without intermediary servers.
- Apache Iceberg on Google Cloud Storage: Eliminates storage fragmentation by persisting Text metadata, Binary BYTES (PDF, PNG), and 768-dimensional float embedding vectors into a single, open Apache Parquet table.
- BigQuery Vector Accelerator: Leverages distributed COSINE_DISTANCE pushdown directly across open Parquet files, executing sub-second semantic retrieval with 100% data sovereignty entirely within the customer's GCP perimeter.

1.1 The Pitfalls of Traditional Vector Architectures

To perform semantic search across these mixed assets, engineering teams typically deploy complex multi-tier pipelines:

Dedicated Vector Database Tax: Specialized vector databases (Pinecone, Weaviate, Qdrant) cost hundreds to thousands of dollars per month, requiring dedicated network infrastructure, VPC peering, and credential rotation.
Metadata Synchronization Drift: When document content changes on Google Drive, keeping the vector database synchronized with external document stores requires complex webhook choreography and distributed transaction handling.
Binary Data Isolation: Most vector databases store only vector embeddings and minimal text metadata, forcing systems to maintain secondary blob storage links that frequently break or drift out of sync.

1.2 The Breakthrough: Apache Iceberg as a Multimodal Vector Store

Apache Iceberg fundamentally redefines this paradigm:

Binary Data Support: Iceberg tables are not restricted to scalar primitives; they natively store arbitrary binary payloads (BYTES) and complex arrays (ARRAY<FLOAT64>). A single open Parquet table can hold document metadata, raw PDF binaries, image bytes, and high-dimensional vector embeddings side by side.
Zero Vendor Lock-In: Assets reside in open Parquet files on Google Cloud Storage, directly queryable by BigQuery, Apache Spark, Trino, or DuckDB.
Serverless Vector Compute: BigQuery provides distributed vector distance functions (COSINE_DISTANCE, EUCLIDEAN_DISTANCE) and vector indexes over Iceberg tables, eliminating the need for standalone vector database servers.

1.3 From Vector Search to Semantic File Discovery: The Power of GAS & `file_id`

One of the most compelling enterprise advantages of implementing this pipeline in Google Apps Script is the direct bridge between AI vector search and live Google Drive file discovery:

In conventional RAG pipelines, vector search engines return isolated text chunks, leaving users stranded with no direct path to the original source document.
In contrast, because IcebergApp stores the authentic Google Drive file_id directly in the Iceberg table schema alongside the PDF binary snapshot, every vector search result includes the authoritative Drive File ID.
This enables Workspace developers to build an intelligent semantic file search engine:
1. One-Click Live Navigation: Users can immediately navigate directly to the matching collaborative asset across formats (Google Docs: https://docs.google.com/document/d/${file_id}/edit, Sheets: https://docs.google.com/spreadsheets/d/${file_id}/edit, Slides: https://docs.google.com/presentation/d/${file_id}/edit, Forms: https://docs.google.com/forms/d/${file_id}/edit, or generic Drive link https://drive.google.com/open?id=${file_id}).
2. Automated Workspace Actionability: In GAS, receiving the file_id allows instant downstream scripting—such as updating document text via DocumentApp, recalculating spreadsheets via SpreadsheetApp, generating slides via SlidesApp, managing form intake via FormApp, or sharing access via DriveApp.getFileById(file_id).addViewer().

By marrying Google Apps Script with Apache Iceberg via IcebergApp, Workspace developers gain not only a multimodal lakehouse but an actionable AI-powered file search engine across their entire Google Drive ecosystem.

2. Architecture & Multimodal Pipeline

The end-to-end processing pipeline—from document ingestion and binary conversion to vector generation and distributed BigQuery search, as well as the autonomous verification flow executed by our test suite—is organized into the 6-stage workflow illustrated in Figure 2.

Figure 2: End-to-End Multimodal Vector Search Lifecycle in Apache Iceberg via Google Apps Script. Displays the 6-stage operational workflow from document normalization to sub-second vector search and safe test suite resource cleanup.

Detailed Operational Walkthrough of Figure 2:

As illustrated across the numbered progression of Figure 2, the system executes an automated, 6-step workflow that coordinates Google Workspace, Gemini AI, BigQuery, and Google Cloud Storage:

Step 1: Document Normalization & Asset Ingestion: The pipeline captures heterogeneous enterprise assets across Google Workspace. When processing live Google Docs, DriveApp.getFileById(docId).getBlob() converts collaborative documents into immutable, standardized PDF binaries (application/pdf) without requiring headless Chromium or external conversion microservices. Concurrently, binary PNG images and raw operational text notes are loaded into memory.
Step 2: Vector Embedding Synthesis: Google Apps Script dispatches the textual payload of each asset (full text for documents and text files; semantic description metadata for images) to Google's Gemini Embedding API (text-embedding-004). The model returns dense, L2-normalized 768-dimensional float arrays (ARRAY<FLOAT64>) that capture semantic meaning across all modalities.
Step 3: Iceberg Parquet Commit via IcebergApp: Leveraging the core IcebergApp.js library, the engine prepares an open Apache Iceberg table on Google Cloud Storage. Through table.insertBlobs(), binary data payloads (BYTES), descriptive schema metadata, and 768-dimensional vector arrays are committed simultaneously into open Parquet data files accompanied by hierarchical Avro metadata manifests.
Step 4: Sub-Second Vector Query: When an operator issues a natural language query (e.g., "How do I automate spreadsheets with JavaScript?"), the query is vectorized via Gemini. BigQuery then executes a distributed vector scan using COSINE_DISTANCE(embedding, query_vector) directly against the Parquet data files stored on Cloud Storage, completely bypassing intermediate database servers.
Step 5: Ranked Multimodal Retrieval: BigQuery ranks all assets deterministically by cosine distance (ORDER BY distance ASC LIMIT 3). The search engine successfully retrieves the most relevant asset regardless of original format (whether PDF document, architectural diagram, or raw text note), achieving high semantic confidence (e.g., similarity scores exceeding 0.87).
Step 6: Test Suite Zero-Residue Cleanup: Upon completion of verification and retrieval, the autonomous test runner purges all temporary test assets: trashing test Google Docs on Google Drive, dropping the test table, and completely deleting the BigQuery dataset and Cloud Storage bucket within 35 seconds. (Note: While production systems naturally retain their data, this self-cleaning teardown is built into the test suite so evaluators can run it with zero lingering cloud cost or clutter.)

2.1 Component Breakdown

Automatic Document Normalization (Google Workspace Docs / Sheets / Slides -> PDF Blob): In Google Apps Script, calling DriveApp.getFileById(fileId).getBlob() on Google Docs, Google Sheets, or Google Slides automatically exports the live collaborative asset into an industry-standard, immutable PDF binary (application/pdf) without external software. (For Google Forms, questions and configurations can be extracted via FormApp or linked response sheets into structured text/blobs.) This allows all dynamic Google Workspace documents to be archived and indexed as reproducible binary snapshots inside Apache Iceberg.
Multimodal Schema Definition: The Iceberg table schema harmonizes structured metadata, binary assets, and vector embeddings:

   CREATE TABLE `my_project.lakehouse_catalog.multimodal_knowledge_assets` (
     id STRING NOT NULL,
     file_id STRING,
     name STRING,
     category STRING,
     mime_type STRING,
     size INT64,
     description STRING,
     data BYTES,
     embedding ARRAY<FLOAT64>,
     updated_at TIMESTAMP
   );

Notice the file_id STRING column: this preserves the primary Google Drive document identifier, serving as the essential bi-directional bridge between the immutable lakehouse Parquet archive and the live Google Drive file.

Automated Dense Vector Synthesis with Gemini (text-embedding-004): IcebergApp interfaces natively with Google's state-of-the-art Gemini Embedding API (text-embedding-004). Extracted body text from Google Docs, tabular summaries from Sheets, slide contents, form structures, binary image metadata summaries, and external web payloads are synthesized into 768-dimensional normalized float vectors (ARRAY<FLOAT64>), persisted directly into the Iceberg table's embedding column.
Sub-Second Vector Search via BigQuery Acceleration: Queries are evaluated using serverless SQL pushdown:

   SELECT
     id, file_id, name, category, mime_type,
     COSINE_DISTANCE(embedding, [0.0142, -0.0521, ...]) AS distance,
     ROUND(1.0 - COSINE_DISTANCE(embedding, [0.0142, -0.0521, ...]), 4) AS similarity
   FROM `my_project.lakehouse_catalog.multimodal_knowledge_assets`
   WHERE embedding IS NOT NULL
   ORDER BY distance ASC
   LIMIT 3;

2.2 How Gemini Powers the Architecture: 3 Core Operational Pillars

Within this architecture, Google Gemini is not merely an optional add-on; it serves as the foundational intelligence engine that transforms a passive storage repository into a cognitive, semantic discovery system. Gemini participates deeply across three key operational dimensions:

1. Ingestion Phase: Harmonizing Heterogeneous Modalities into a Unified 768-D Semantic Space

Traditional storage engines cannot compare a PDF document, an architectural PNG image, a spreadsheet, and an external web page because their underlying data primitives are fundamentally incompatible.

Documents & Text Assets (Docs, Sheets, Slides, Forms, Web): Within Google Apps Script, DocumentApp and native Workspace APIs extract raw text representations, which IcebergApp dispatches to the Gemini Embedding API (text-embedding-004).
Visual Artifacts (Images & Diagrams): Structural summaries and descriptive metadata are supplied to the embedding engine.
Gemini's Role: Gemini analyzes the semantic content and projects each disparate asset into an identical 768-dimensional L2-normalized float array (ARRAY<FLOAT64>). By doing so, every asset—regardless of whether it originated as a 30-page PDF, a flowchart image, or an HTML snippet—shares the exact same mathematical coordinate system inside the open Iceberg Parquet table.

2. Query Phase: Real-Time Translation of Natural Language into Calculable Query Vectors

When an operator issues a natural language query from Google Apps Script (e.g., "How do I automate spreadsheets with JavaScript?"):

IcebergApp.getTableByName().searchSimilar(query) immediately makes an outbound REST call to Gemini's embedContent endpoint via Apps Script's native UrlFetchApp.
Within 200 to 300 milliseconds, Gemini returns a 768-dimensional query vector that captures the user's conceptual intent.
This vector is injected into BigQuery's distributed SQL engine, allowing COSINE_DISTANCE(embedding, [queryVector]) to scan thousands of records in parallel with sub-second execution latency.

3. Breaking Keyword Barriers: True Semantic Understanding Without Exact-Word Matches

Legacy Google Drive search and relational SQL LIKE queries fail whenever documents use synonyms or alternative technical phrasing.

Gemini's Semantic Breakthrough: Gemini understands cross-domain conceptual hierarchies. As demonstrated in our empirical execution log (Section 5.1), when queried with the complex physical concept "superconducting qubit coherence at millikelvin temperatures", the system correctly identified TXT-001 (Quantum Computing Guide) with an outstanding similarity score of 0.8669, cleanly separating it from unrelated biological research or operational guides despite the lack of exact title matches.
Pure Serverless Simplicity: While conventional vectorization pipelines require heavyweight Python environments (PyTorch, Hugging Face Transformers) running on GPU clusters, IcebergApp achieves state-of-the-art embedding generation through a single serverless HTTPS call, incurring zero persistent infrastructure costs.

3. Implementation: The Test Suite & Code Essence

To provide a fully verified, turn-key demonstration, the complete standalone test script is implemented at src/multimodal_vector_search_test.js.

3.1 Step 1: Install IcebergApp in Google Apps Script

To use IcebergApp in your project:

Open your Google Apps Script project (via script.new or container-bound to a Sheet/Doc).
Download the core library IcebergApp.js from GitHub:

   https://github.com/tanaikech/IcebergApp/blob/master/src/IcebergApp.js

In the Apps Script editor, create a new script file named IcebergApp.gs (or IcebergApp.js) and paste the complete library content.
Under Services (+), add the BigQuery API (v2).
Open Project Settings (⚙️) > Script properties, and configure:
- PROJECT_ID: Your Google Cloud Project ID.
- REGION: Your target region (e.g., asia-northeast1).
- GEMINI_API_KEY: Your Gemini API key from Google AI Studio.

3.2 Step-by-Step Test Execution: What Was Obtained at Each Stage

By inspecting the empirical execution log produced by runMultimodalVectorSearchTest(), we can trace exactly what technical artifacts and verification milestones were obtained across each of the 6 sequential stages:

Stage 1 [00:00:04]: Ephemeral Infrastructure Provisioning
- Action: Provisioned an isolated BigQuery dataset lakehouse_multimodal_xxxx at asia-northeast1 and a Cloud Storage bucket gs://lakehouse-mm-xxxx with Uniform Bucket-Level Access.
- What Was Obtained: A completely isolated, timestamped GCP sandbox environment. This guarantees that test operations never interfere with production datasets or existing lakehouse catalogs.
Stage 2 [00:00:08]: Apache Iceberg Table Initialization
- Action: Dispatched DDL statements via BigQuery's BigLake external catalog integration to establish the Iceberg table multimodal_knowledge_assets.
- What Was Obtained: A unified, open table schema natively supporting binary payloads (data BYTES), high-dimensional embeddings (embedding ARRAY<FLOAT64>), and standard metadata (id, name, category, mime_type, size, description).
Stage 3 [00:00:10]: Google Docs Generation & Cross-Modal Asset Staging
- Action: Dynamically generated 3 live Google Docs on Google Drive, immediately converted them to immutable PDF blobs via DriveApp.getFileById().getBlob(), and staged 2 raw text notes and 1 binary PNG diagram.
- What Was Obtained: Six concrete multimodal assets across three distinct formats with verified byte-level sizes:
  - DOC-001: Google_Apps_Script_Automation_Guide.pdf (27,177 bytes, application/pdf)
  - DOC-002: Google_Sheets_Calculations_Analytics_Guide.pdf (28,363 bytes, application/pdf)
  - DOC-003: Google_Docs_Collaborative_Publishing_Guide.pdf (20,757 bytes, application/pdf)
  - TXT-001: quantum_cryogenic_computing_whitepaper.txt (229 bytes, text/plain)
  - TXT-002: marine_ocean_bioluminescence_study.txt (218 bytes, text/plain)
  - IMG-001: lakehouse_multimodal_architecture_diagram.png (70 bytes, image/png)
Stage 4 [00:00:15 – 00:00:24]: Gemini Vector Synthesis & Single-Table Parquet Commit
- Action: Dispatched the textual payloads and descriptive summaries to Google's Gemini Embedding API (text-embedding-004), generated 768-dimensional float arrays, and executed table.insertBlobs().
- What Was Obtained: All 6 heterogeneous records—unifying binary bytes, structured metadata, and vector embeddings—were committed into a single open Parquet data file and updated Avro metadata manifests on Cloud Storage in just 9 seconds. The ingested inventory was printed and verified.
Stage 5 [00:00:24 – 00:00:29]: Semantic Vector Searches across Heterogeneous Formats
- Action: Executed 4 distinct natural language queries using BigQuery distributed COSINE_DISTANCE pushdown directly over the Iceberg Parquet files.
- What Was Obtained: 100% precision in cross-modal ranking; every target asset achieved Rank #1 with statistically significant margin over alternative files:
  - Query 1 (Automation): Isolated DOC-001 (0.7500 similarity) vs Sheets PDF (0.6324).
  - Query 2 (Formulas): Isolated DOC-002 (0.7935 similarity) vs GAS PDF (0.5748).
  - Query 3 (Quantum Qubits): Isolated TXT-001 (0.8669 similarity) vs Biology text (0.5012).
  - Query 4 (Visual Flow Diagram): Isolated IMG-001 (0.8762 similarity) vs Docs PDF (0.6724).
Stage 6 [00:00:29 – 00:00:35]: Absolute Zero-Residue Teardown
- Action: Automatically dropped the Iceberg table, trashed the 3 Google Docs by explicit Drive ID ([xxxx-drive-doc1-id], etc.), deleted the BigQuery dataset, and destroyed the Cloud Storage bucket.
- What Was Obtained: 100% eradication of all transient cloud resources in only 6 seconds, leaving zero leftover data, zero storage costs, and zero orphaned Drive files.

3.3 Step 2: Code Essence – Ingesting Mixed Assets

The following concise snippet demonstrates how easy it is to ingest mixed Google Docs (PDFs), direct text, and binary images using IcebergApp:

function ingestMultimodalAssets() {
  const projectId = "your-gcp-project-id";
  const catalogName = "lakehouse_multimodal";
  const tableName = "knowledge_assets";

  // 1. Initialize Iceberg catalog
  const app = IcebergApp.openByCatalog(
    projectId,
    catalogName,
    "asia-northeast1",
  ).ensureCatalog();
  const table = app.createAssetTable(tableName);

  // 2. Prepare Google Doc (auto-exported to PDF)
  const doc = DocumentApp.create("GAS_Automation_Guide");
  doc
    .getBody()
    .setText(
      "Google Apps Script automates Workspace workflows and connects to Apache Iceberg.",
    );
  doc.saveAndClose();
  const pdfBlob = DriveApp.getFileById(doc.getId())
    .getBlob()
    .setName("GAS_Automation_Guide.pdf");

  // 3. Prepare Direct Plain Text
  const textBlob = Utilities.newBlob(
    "Superconducting transmon qubits operate at 10 millikelvin inside dilution refrigerators.",
    "text/plain",
    "quantum_physics.txt",
  );

  // 4. Ingest with automated Gemini vector embeddings
  const entries = [
    {
      blob: pdfBlob,
      metadata: {
        id: "DOC-001",
        file_id: doc.getId(),
        category: "google_doc_pdf",
        description:
          "Google Apps Script automation and cloud lakehouse connectivity guide.",
      },
    },
    {
      blob: textBlob,
      metadata: {
        id: "TXT-001",
        category: "plain_text",
        description: textBlob.getDataAsString(),
      },
    },
  ];

  const insertedCount = table.insertBlobs(entries, { embed: true });
  console.log(
    `Ingested ${insertedCount} multimodal records into Apache Iceberg.`,
  );
}

3.4 Code Essence – Semantic Vector Search & Live File Discovery

Executing semantic vector search across both PDF documents and plain text files requires only a single method call. Crucially, because file_id is queried directly alongside distance metrics, the result connects straight back to the live Google Drive document:

function searchMultimodalLakehouse() {
  const app = IcebergApp.openByCatalog(
    "your-gcp-project-id",
    "lakehouse_multimodal",
  );
  const table = app.getTableByName("knowledge_assets");

  const query =
    "How do I build serverless data pipelines in Workspace using JavaScript?";

  // Request file_id alongside metadata and similarity metrics
  const results = table.searchSimilar(query, {
    topK: 3,
    columns: ["id", "file_id", "name", "category", "mime_type"],
  });

  results.forEach((row, i) => {
    if (i === 0) {
      console.log(`Rank | ${row.join(" | ")}`);
    } else {
      const [id, fileId, name, category, mimeType, distance, similarity] = row;
      const driveUrl = fileId
        ? `https://docs.google.com/document/d/${fileId}/edit`
        : "N/A (direct text/image)";
      console.log(
        ` #${i} | ID: ${id} | Name: ${name} | Similarity: ${similarity}`,
      );
      console.log(`      🔗 Live Google Drive Document: ${driveUrl}`);

      // Optional: Programmatically open or share the matching live Google Doc
      if (fileId) {
        const liveDoc = DocumentApp.openById(fileId);
        console.log(`      📄 Document Title: "${liveDoc.getName()}"`);
      }
    }
  });
}

4. Test Suite Safety Design: Automated Cleanup of Test Resources

For developers who wish to evaluate this multimodal lakehouse architecture within their own Google Cloud and Google Drive environments, the accompanying autonomous test script (multimodal_vector_search_test.js) incorporates an automated self-cleaning mechanism to ensure that temporary test assets (test Google Docs, temporary BigQuery datasets, and temporary GCS buckets) are completely scrubbed.

[!NOTE]
Production vs. Testing Context: While real-world production lakehouses naturally preserve accumulated tables and documents, this cleanup engine is implemented exclusively in the test suite so that developers can safely run and evaluate the pipeline without leaving orphaned test clutter or incurring unexpected cloud maintenance costs.

When running automated test suites in serverless environments, an execution timeout (e.g., Apps Script's 6-minute ceiling) or manual cancellation could risk leaving temporary test resources uncollected. To eliminate this risk, the test script implements a Triple-Tiered Safety Architecture:

Persistent ScriptProperties Registry (_ICEBERG_MULTIMODAL_TEST_REGISTRY_): The instant a test Google Doc, BigQuery dataset, GCS bucket, or table is created, its identifier is committed immediately to persistent ScriptProperties.
Pre-Flight Sweep: Upon invoking runMultimodalVectorSearchTest(), the runner first reads the registry and scrubs any lingering resources from previously aborted runs, followed by a wildcard Drive search for test-pattern titles.
Standalone Emergency Purge Function (purgeResidualMultimodalTestResources): A dedicated function executable directly from the Apps Script toolbar dropdown to purge all tracked test resources on demand without re-running the full test suite.

function purgeResidualMultimodalTestResources() {
  console.log(
    "🧹 Running Standalone Emergency Purge for Multimodal Test Resources...",
  );
  cleanupResidualMultimodalResources_();
  console.log(
    "✨ Emergency purge complete. All residual artifacts 100% purged.",
  );
}

5. Execution Results & Empirical Log Audit

When runMultimodalVectorSearchTest() is executed in the Apps Script Editor, it sequentially carries out:

Isolated infrastructure provisioning (dataset & bucket).
Creation of three live Google Docs on Google Drive and immediate conversion into PDF binary blobs.
Preparation of direct text files and image assets.
Batch ingestion into Apache Iceberg with Gemini 768-dimensional vector embeddings.
Execution of 4 diverse semantic vector queries targeting distinct domains (Google Apps Script, Google Sheets, Quantum Physics, Architecture Diagrams).
Comprehensive post-test zero-residue teardown.

5.1 Empirical Live Execution Log

The following execution log is the output produced by executing runMultimodalVectorSearchTest within the Google Apps Script V8 runtime against Google Cloud Platform (with private identifiers masked for privacy, conforming to article conventions):

00:00:00    Notice  Execution started
00:00:01    Info    🚀 Starting Multimodal Apache Iceberg Vector Search Test Suite...
00:00:02    Info    📋 Active Target Environment: Project [your-gcp-project-id], Region [asia-northeast1], Gemini API [Configured]
00:00:04    Info
--- [1/6] Provisioning Isolated Dataset [lakehouse_multimodal_xxxx] & GCS Bucket [lakehouse-mm-xxxx] ---
00:00:08    Info    ✅ Base Storage Provisioned: gs://lakehouse-mm-xxxx
00:00:08    Info
--- [2/6] Creating Apache Iceberg Asset Table [multimodal_knowledge_assets] ---
00:00:08    Info    ✅ Dataset [lakehouse_multimodal_xxxx] confirmed at [asia-northeast1].
00:00:09    Info    ✅ Dataset [lakehouse_multimodal_xxxx] confirmed at [asia-northeast1].
00:00:10    Info    ✅ Iceberg Table Ready: `your-gcp-project-id.lakehouse_multimodal_xxxx.multimodal_knowledge_assets`
00:00:10    Info
--- [3/6] Generating Real Google Docs on Google Drive & Exporting to PDF ---
00:00:11    Info    📄 Created Google Doc 1: "Google_Apps_Script_Automation_Guide_xxxx" -> Converted to PDF (27177 bytes)
00:00:14    Info    📄 Created Google Doc 2: "Google_Sheets_Calculations_Analytics_Guide_xxxx" -> Converted to PDF (28363 bytes)
00:00:15    Info    📄 Created Google Doc 3: "Google_Docs_Collaborative_Publishing_Guide_xxxx" -> Converted to PDF (20757 bytes)
00:00:15    Info    📝 Prepared Direct Text 1: "quantum_cryogenic_computing_whitepaper.txt" (229 bytes)
00:00:15    Info    📝 Prepared Direct Text 2: "marine_ocean_bioluminescence_study.txt" (218 bytes)
00:00:15    Info    🖼️ Prepared Binary Image: "lakehouse_multimodal_architecture_diagram.png" (70 bytes)
00:00:15    Info
--- [4/6] Ingesting Multimodal Assets into Apache Iceberg with Gemini Vector Embeddings ---
00:00:23    Info    ✅ Successfully ingested 6 multimodal assets into Apache Iceberg with 768-dim embeddings!
00:00:24    Info
--- Ingested Lakehouse Asset Inventory ---
00:00:24    Info     [0] id | name | category | mime_type | size
00:00:24    Info     [1] DOC-002 | Google_Sheets_Calculations_Analytics_Guide.pdf | google_doc_pdf | application/pdf | 28363
00:00:24    Info     [2] DOC-001 | Google_Apps_Script_Automation_Guide.pdf | google_doc_pdf | application/pdf | 27177
00:00:24    Info     [3] DOC-003 | Google_Docs_Collaborative_Publishing_Guide.pdf | google_doc_pdf | application/pdf | 20757
00:00:24    Info     [4] IMG-001 | lakehouse_multimodal_architecture_diagram.png | image_diagram | image/png | 70
00:00:24    Info     [5] TXT-001 | quantum_cryogenic_computing_whitepaper.txt | plain_text | text/plain | 229
00:00:24    Info     [6] TXT-002 | marine_ocean_bioluminescence_study.txt | plain_text | text/plain | 218
00:00:24    Info
--- [5/6] Executing Semantic Vector Searches across Mixed Data Types ---
00:00:24    Info
================================================================================
00:00:24    Info    🔍 [Query 1/4] Test A: Target Google Apps Script Automation (Expecting DOC-001 / Google Apps Script PDF)
00:00:24    Info       Prompt: "How can I automate spreadsheet workflows and trigger cloud tasks using JavaScript?"
00:00:24    Info    ================================================================================
00:00:25    Info    Rank | ID      | Category       | MIME Type        | Distance | Similarity | Asset Name
00:00:25    Info    -----+---------+----------------+------------------+----------+------------+--------------------------------------------------
00:00:25    Info     #1  | DOC-001 | google_doc_pdf | application/pdf  |  0.2500  |   0.7500   | Google_Apps_Script_Automation_Guide.pdf
00:00:25    Info     #2  | DOC-002 | google_doc_pdf | application/pdf  |  0.3676  |   0.6324   | Google_Sheets_Calculations_Analytics_Guide.pdf
00:00:25    Info     #3  | DOC-003 | google_doc_pdf | application/pdf  |  0.4319  |   0.5681   | Google_Docs_Collaborative_Publishing_Guide.pdf
00:00:25    Info
================================================================================
00:00:25    Info    🔍 [Query 2/4] Test B: Target Google Sheets Calculations (Expecting DOC-002 / Google Sheets PDF)
00:00:25    Info       Prompt: "Spreadsheet calculation formulas, pivot tables, and grid data analysis for large workbooks"
00:00:25    Info    ================================================================================
00:00:26    Info    Rank | ID      | Category       | MIME Type        | Distance | Similarity | Asset Name
00:00:26    Info    -----+---------+----------------+------------------+----------+------------+--------------------------------------------------
00:00:26    Info     #1  | DOC-002 | google_doc_pdf | application/pdf  |  0.2065  |   0.7935   | Google_Sheets_Calculations_Analytics_Guide.pdf
00:00:26    Info     #2  | DOC-001 | google_doc_pdf | application/pdf  |  0.4252  |   0.5748   | Google_Apps_Script_Automation_Guide.pdf
00:00:26    Info     #3  | IMG-001 | image_diagram  | image/png        |  0.4325  |   0.5675   | lakehouse_multimodal_architecture_diagram.png
00:00:26    Info
================================================================================
00:00:26    Info    🔍 [Query 3/4] Test C: Target Quantum Physics Text (Expecting TXT-001 / Quantum Whitepaper)
00:00:26    Info       Prompt: "Superconducting qubits, Josephson junctions, and dilution refrigerators operating at millikelvin temperatures"
00:00:26    Info    ================================================================================
00:00:28    Info    Rank | ID      | Category       | MIME Type        | Distance | Similarity | Asset Name
00:00:28    Info    -----+---------+----------------+------------------+----------+------------+--------------------------------------------------
00:00:28    Info     #1  | TXT-001 | plain_text     | text/plain       |  0.1331  |   0.8669   | quantum_cryogenic_computing_whitepaper.txt
00:00:28    Info     #2  | TXT-002 | plain_text     | text/plain       |  0.4988  |   0.5012   | marine_ocean_bioluminescence_study.txt
00:00:28    Info     #3  | IMG-001 | image_diagram  | image/png        |  0.5016  |   0.4984   | lakehouse_multimodal_architecture_diagram.png
00:00:28    Info
================================================================================
00:00:28    Info    🔍 [Query 4/4] Test D: Target Architecture Diagram (Expecting IMG-001 / System Diagram)
00:00:28    Info       Prompt: "Visual architectural flow diagram showing multimodal lakehouse ingestion into Google Cloud Storage"
00:00:28    Info    ================================================================================
00:00:29    Info    Rank | ID      | Category       | MIME Type        | Distance | Similarity | Asset Name
00:00:29    Info    -----+---------+----------------+------------------+----------+------------+--------------------------------------------------
00:00:29    Info     #1  | IMG-001 | image_diagram  | image/png        |  0.1238  |   0.8762   | lakehouse_multimodal_architecture_diagram.png
00:00:29    Info     #2  | DOC-001 | google_doc_pdf | application/pdf  |  0.3276  |   0.6724   | Google_Apps_Script_Automation_Guide.pdf
00:00:29    Info     #3  | DOC-003 | google_doc_pdf | application/pdf  |  0.4567  |   0.5433   | Google_Docs_Collaborative_Publishing_Guide.pdf
00:00:29    Info
🎉 ALL MULTIMODAL VECTOR SEARCH TESTS COMPLETED WITH 100% SUCCESS!
00:00:29    Info
--- [6/6] ABSOLUTE CLEANUP: Purging Ephemeral Test Resources ---
00:00:30    Info    🗑️ Dropped Iceberg Table: multimodal_knowledge_assets
00:00:30    Info    🗑️ Trashed Google Doc: [xxxx-drive-doc1-id]
00:00:31    Info    🗑️ Trashed Google Doc: [xxxx-drive-doc2-id]
00:00:31    Info    🗑️ Trashed Google Doc: [xxxx-drive-doc3-id]
00:00:32    Info    🗑️ Removed BigQuery Dataset: lakehouse_multimodal_xxxx
00:00:34    Info    🗑️ Deleted GCS Bucket: gs://lakehouse-mm-xxxx
00:00:35    Info    ✨ Multimodal test cleanup complete. Zero residue on Drive, BigQuery, and GCS.
00:00:34    Notice  Execution completed

5.2 Rigorous Empirical Audit & Evaluation

The empirical execution log confirms four pivotal architectural milestones:

Flawless End-to-End Execution Latency (35 Seconds Total):
The complete sequence—spanning isolated GCP infrastructure provisioning, live document creation on Google Drive, PDF binary conversion, Gemini embedding generation, Parquet writing, four full BigQuery distributed vector searches, and complete resource teardown—completed in approximately 35 seconds. This consumes only 9.7% of the Google Apps Script 6-minute ceiling, proving high operational headroom.
Cross-Modal Semantic Discrimination:
Across all four test queries, the target assets were ranked #1 with statistically significant margin:
- Query 1 (Apps Script Automation): Correctly isolated DOC-001 (Google_Apps_Script_Automation_Guide.pdf) with distance 0.2500 (similarity 0.7500), clearly outranking the Sheets guide (0.6324) and Docs guide (0.5681).
- Query 2 (Spreadsheet Formulas & Pivot Tables): Matched DOC-002 (Google_Sheets_Calculations_Analytics_Guide.pdf) as #1 with similarity 0.7935, demonstrating fine-grained semantic separation between distinct Workspace tools.
- Query 3 (Superconducting Quantum Qubits): Matched the raw text whitepaper TXT-001 with an outstanding similarity of 0.8669 (distance 0.1331), cleanly distinguishing physics from the unrelated biological text (0.5012).
- Query 4 (Visual System Architecture Diagram): Matched IMG-001 (lakehouse_multimodal_architecture_diagram.png) as #1 with similarity 0.8762, proving that binary image assets with descriptive metadata participate seamlessly in unified semantic search alongside textual documents.
True Multimodal Storage Coexistence:
The table inventory confirms that 28KB PDF documents, 70B image binaries, and 200B text files coexist within the identical Iceberg table schema on Google Cloud Storage, unified under standard 768-dimensional float embeddings.
Test Suite Safety Verification (Zero Residual Clutter):
The post-test cleanup phase verified the immediate destruction of all temporary verification assets:
- The test Iceberg table multimodal_knowledge_assets.
- All three test Google Docs by explicit Drive File ID ([xxxx-drive-doc1-id], [xxxx-drive-doc2-id], [xxxx-drive-doc3-id]).
- The test BigQuery dataset lakehouse_multimodal_xxxx.
- The test Cloud Storage bucket gs://lakehouse-mm-xxxx. Zero orphaned files or uncollected storage charges remain for the evaluator.

6. Architectural Evaluation & Cost Comparison

Dimension	Dedicated Vector DB (Pinecone / Milvus)	Custom Microservice + Cloud SQL	IcebergApp Multimodal Lakehouse
Hosting Infrastructure	Dedicated Cloud Instance or SaaS Cluster	GKE / Cloud Run + Cloud SQL PostgreSQL (pgvector)	100% Serverless (GAS + BigQuery + GCS)
Monthly Base Cost	$500 – $3,000 / month	$150 – $600 / month	$0.00 (Pure Pay-per-Query On-Demand)
Binary Payload Storage	Not Supported (External S3/GCS required)	External S3/GCS required	Native in Table (`BYTES` / Storage URI)
Google Drive Integration	Webhooks + Complex OAuth Microservice	Scheduled Batch Ingestion Cron Jobs	Native 1-Line Ingestion (`DriveApp` + `IcebergApp`)
Document Versioning	Manual vector ID tracking	Custom relational snapshot tables	Native Iceberg Snapshots & Time Travel
Query Engine Interoperability	Proprietary Vector API only	SQL (pgvector)	Open Standard (BigQuery, Spark, Trino, DuckDB)

7. Conclusion

By combining Google Apps Script with Apache Iceberg and the Gemini embedding model, developers are no longer constrained by the traditional boundaries between structured spreadsheets, unstructured documents, and dedicated vector databases.

True Multimodality: Apache Iceberg's native binary support (BYTES) allows Google Workspace assets (Docs, Sheets, Slides via automatic PDF export, and Forms), diagrams, and text records to live together in a single open Parquet table.
Elimination of SaaS Subscriptions: Zero recurring fees for dedicated vector database infrastructure; queries execute on-demand with BigQuery acceleration.
Turn-Key Accessibility: With IcebergApp, any Google Workspace developer can deploy a production-grade multimodal lakehouse vector engine using standard JavaScript.
AI-Driven Google Drive File Discovery: Because file_id is preserved directly in the schema, vector search serves as an intelligent semantic file finder across Google Docs, Sheets, Slides, and Forms—allowing users to navigate directly to live collaborative assets and enabling scripts to trigger downstream Workspace automation (DocumentApp, SpreadsheetApp, SlidesApp, FormApp, DriveApp).

References & Resources

GitHub Repository: https://github.com/tanaikech/IcebergApp
Core Library Source: IcebergApp.js
Multimodal Test Suite Source: multimodal_vector_search_test.js
Companion Article 1 (Foundational Architecture): Unifying Google Workspace and Apache Iceberg: Serverless Lakehouse Management
Apache Iceberg Specification: https://iceberg.apache.org/spec/
Google Cloud BigQuery Iceberg Documentation: https://cloud.google.com/bigquery/docs/iceberg-tables
Gemini Embeddings API Documentation: https://ai.google.dev/gemini-api/docs/embeddings

Unifying Google Workspace and Apache Iceberg: Serverless Lakehouse Management

Tanaike — Sun, 06 Sep 2026 07:35:05 +0000

Turn Google Sheets into a Petabyte Lakehouse with Sub-Second ACID Queries.

Abstract

Google Sheets faces severe scalability bottlenecks when handling large enterprise datasets, including a strict 10-million cell limit, crippling CRUD latency, and Google Apps Script's execution and memory boundaries. This article presents IcebergApp, an open-source library bridging Google Workspace to Apache Iceberg lakehouses on Google Cloud. By utilizing BigQuery as a serverless query accelerator to execute predicate pushdown over Iceberg metadata, IcebergApp eliminates spreadsheet latency, ensures ACID transactions, and enables sub-second queries, time travel, and agentic AI integration directly from Google Apps Script.

Introduction

Modern enterprise data architectures are rapidly converging on open table formats. Among them, Apache Iceberg has emerged as the de facto industry standard for managing massive analytical datasets on object storage (Apache Iceberg Documentation). Google Cloud has accelerated this paradigm shift by introducing the Borderless Lakehouse architecture and native support for Apache Iceberg tables within BigQuery (BigQuery Iceberg Documentation).

Traditionally, data lakes stored unstructured or semi-structured files directly on object storage like Google Cloud Storage (GCS). While cost-effective, this approach introduced significant operational bottlenecks:

Directory listings suffered from high I/O latency as file counts scaled into the millions.
Multi-engine concurrent writes lacked ACID transaction guarantees, leading to dirty reads and corrupt states.
Schema evolution and in-place row updates required full table rewrites.

Apache Iceberg eliminates these limitations by introducing a hierarchical metadata tree (Manifest Lists and Manifest Files) that manages snapshots independently of the physical file layout (Apache Iceberg Specification). Query engines can evaluate partition boundaries and column-level min/max statistics entirely within this metadata layer. This technique, known as Predicate Pushdown, prunes irrelevant data files before a single byte of actual storage is scanned.

Figure 1: The Apache Iceberg hierarchical metadata tree. Query engines inspect the Catalog and Table Metadata to evaluate Manifest Lists, using column statistics to prune unneeded Manifest Files and skip irrelevant Parquet data files.

As illustrated in Figure 1, Apache Iceberg organizes table state into four distinct, immutable layers:

Catalog Layer (Top): The BigQuery or Iceberg REST Catalog maintains the current active pointer to the latest table metadata file.
Table Metadata File (vN.metadata.json): Defines the table schema, partition specs, and an append-only log of snapshot historical states.
Manifest List (snap-XYZ.avro): Records all manifest files that compose a specific snapshot, along with each manifest's partition range boundaries.
Manifest Files (*.avro) & Parquet Data Files (Bottom): Manifest files hold row-level file paths and column-level summary statistics (Min/Max values, null counts). When a query executes, Predicate Pushdown evaluates column filters directly against these manifest statistics—flagging irrelevant data files as skipped (shown on the bottom left) and scanning only the files containing relevant rows (highlighted in green on the bottom right).

Motivation: Why Google Apps Script Needs Apache Iceberg

To understand why uniting Google Apps Script with Apache Iceberg is vital, consider how modern enterprises actually handle frontline data:

The "Spreadsheet-as-a-Database" Dilemma: Google Sheets is the most accessible, collaborative data interface in business. Millions of automated workflows rely on Google Apps Script to ingest Google Forms submissions, IoT telemetry, ERP reports, and transactional records directly into spreadsheets. However, treating Google Sheets as a production database inevitably leads to failure: workbooks quickly hit the hard 10-million cell limit, getValues() / setValues() operations suffer multi-second freezes from formula recalculations, and V8 runtime heap exhaustion occurs.
The Pitfalls of Traditional Database Workarounds for GAS: When developers attempt to migrate data out of Sheets into external databases, serverless GAS introduces steep hurdles:
- Relational Databases (Cloud SQL / MySQL / PostgreSQL): Require persistent JDBC connections, VPC tunneling, or static IP whitelisting—mechanisms that serverless Apps Script cannot natively support without complex proxy middleware—along with expensive, 24/7 provisioned database instances.
- Proprietary Data Warehouses: Incur high ingestion costs, lock organizations into closed ecosystems, and impose restrictive quotas on frequent row-level DML updates.
- Raw Object Storage (GCS / Parquet / CSV): While cost-effective, raw storage lacks ACID transaction guarantees, schema enforcement, and concurrent write safety. Attempting to parse raw Parquet files in GAS exhausts runtime quotas within seconds.
The Apache Iceberg Breakthrough: Apache Iceberg solves every one of these pain points simultaneously:
- Zero Vendor Lock-In: Data resides as open Parquet files in customer-owned Cloud Storage, concurrently accessible by Spark, Trino, and Snowflake.
- ACID Transaction Guarantees: Multiple Apps Script triggers, web apps, and data pipelines can write simultaneously without lock contention or data corruption.
- Serverless Metadata Acceleration: Hierarchical metadata enables sub-second Predicate Pushdown, keeping Apps Script memory consumption constant ($O(1)$) and queries within 1–2 seconds.
- Snapshot Isolation & Audit Recovery: Native time-travel snapshots protect against accidental spreadsheet overwrites, restoring historical ground truth in seconds without database downtime.
Democratizing Apache Iceberg for GAS Developers (Effortless Accessibility): While Apache Iceberg provides an enterprise-grade lakehouse specification, it has traditionally been confined to heavy data engineering ecosystems requiring Java, Scala, Python (PyIceberg), or distributed engines like Spark and Trino. For Google Apps Script developers, interacting with Iceberg directly meant untangling complex REST catalog endpoints, managing low-level BigQuery Lakehouse API payloads, and dealing with intricate Avro/Parquet serialization. Therefore, a primary motivation of this project is to make Apache Iceberg effortlessly accessible within Google Apps Script. By wrapping complex catalog coordination and SQL DML generation into a fluent, spreadsheet-native JavaScript interface (table.insertValues(), table.getValues(), table.asOf()), any Workspace developer can deploy and manage enterprise lakehouses in minutes without managing servers or deep data engineering tooling.

Despite these technological leaps, a critical gap persists: business users and automation workflows live inside Google Workspace. Frontline operations run on Google Sheets, while automated pipelines rely heavily on Google Apps Script (GAS). Until now, querying or mutating enterprise Iceberg tables from Apps Script required setting up complex intermediary microservices, managing specialized JDBC drivers, or writing verbose API wrappers.

To bridge this architectural disparity, I developed IcebergApp. Built on top of the BigQuery Advanced Service and Google Cloud's serverless runtime catalog, IcebergApp provides a fluent, spreadsheet-native interface that allows Apps Script developers to manage, query, mutate, and export Apache Iceberg tables with absolute simplicity.

Architecture of IcebergApp

Figure 2: End-to-end architecture of IcebergApp. Frontline Google Workspace applications connect via Apps Script to BigQuery's distributed engine, orchestrating Parquet data and Avro metadata on Google Cloud Storage.

IcebergApp operates by decoupling compute from storage, honoring the first principles of the Lakehouse paradigm. As depicted in Figure 2, the architecture is structured into three coordinated tiers:

Presentation & Application Layer (Top): Business users interact through standard Google Workspace tools—Google Sheets, Forms, and Docs.
Client Library & Orchestration Layer (Middle): IcebergApp runs natively inside the Google Apps Script V8 runtime, translating high-level JavaScript calls and 2D arrays into optimized SQL DML statements without requiring external servers.
Compute & Storage Decoupled Tier (Bottom): Apps Script delegates compute execution to BigQuery, which acts as a serverless query accelerator. BigQuery interfaces with the Iceberg REST Catalog, performs metadata-driven file pruning, and reads/writes Parquet files and Avro metadata stored in customer-owned Google Cloud Storage buckets.

Instead of forcing the Apps Script V8 runtime to download and parse low-level Avro metadata directly—which would quickly exhaust the 6-minute script execution limit and memory quotas—IcebergApp orchestrates BigQuery as a serverless distributed query accelerator. BigQuery inspects the Iceberg REST catalog and metadata tree, performs file pruning, and returns only the finalized, structured records back to Google Apps Script as lightweight 2D arrays.

Figure 3: Performance contrast between traditional client-side data parsing in Apps Script and IcebergApp's serverless BigQuery acceleration.

Figure 3 illustrates the vital performance breakthrough achieved by this architecture:

Traditional Direct Processing (Left Panel): If Apps Script attempts to process large lakehouse datasets directly, the V8 runtime must download massive Avro metadata trees and raw Parquet files over network I/O. This immediately causes V8 memory heap exhaustion ("Exceeded memory limit"), incurs unbounded $O(N)$ client latency, and inevitably triggers the fatal 6-minute execution timeout.
IcebergApp + BigQuery Serverless Accelerator (Right Panel): By delegating heavy compute to BigQuery, Apps Script retains a constant $O(1)$ memory footprint. BigQuery performs parallel partition pruning and instant metadata resolution across Google Cloud's distributed infrastructure, streaming structured results directly into Google Sheets in just 1–2 seconds regardless of whether the target table holds 10 thousand or 100 million records.

In-Depth Latency & Architectural Evaluation: Why BigQuery Accelerates Search

To rigorously understand why routing queries through the BigQuery API yields dramatically lower search latency than native Apps Script processing, consider the underlying physical and distributed execution mechanics:

Metadata-Driven Predicate Pushdown: Iceberg manifest files store column-level summary statistics (minimum and maximum values per data file). When a query includes a filter (e.g., WHERE temperature > 80.0), BigQuery evaluates these boundaries entirely within the metadata tier, skipping 90%–99.9% of Parquet data files on Cloud Storage without reading a single byte of storage payload.
Columnar Projection Pruning: In wide tables (e.g., 50 columns), requesting only two fields (columns: ["device_name", "temperature"]) instructs BigQuery to issue HTTP Range Requests solely for the relevant column chunks within Parquet files, reducing network I/O by up to 96%.
Jupiter Petabit Interconnect & Vectorized C++ Engine: BigQuery and Cloud Storage reside within Google's internal datacenter fabric (Jupiter network), operating at petabit-per-second bisection bandwidth with sub-millisecond inter-rack latency. BigQuery’s C++ Dremel engine decompresses and processes Parquet records in parallel using SIMD vector instructions, filtering millions of rows in hundreds of milliseconds.
Minimizing Client Transfer Payloads ($O(N) \to O(k)$): Instead of downloading raw gigabytes of Parquet files into the GAS V8 sandbox, Apps Script receives only the final, filtered result set ($k$ records) formatted as clean JSON. Client-side memory and CPU consumption drop to near zero.

Rigorous Benchmark Comparison across Architectural Baselines

Dimension	Baseline A: Direct GCS/Parquet in GAS	Baseline B: Large Google Sheets (`getValues`)	IcebergApp (BigQuery Accelerator)
Execution Engine	Single-threaded GAS V8 Sandbox	GAS V8 + Spreadsheet Calculation Engine	BigQuery Distributed MPP (Thousands of Slots)
Network Proximity	Public/Internal API to GCS	Internal Google Sheets RPC	Google Jupiter Petabit Datacenter Fabric
I/O Filtering	Full binary download of Parquet/Avro	Full sheet serialized into memory	Metadata-level Predicate Pushdown + Column Pruning
Memory Footprint	Exceeds V8 heap limit ("Exceeded memory limit")	Saturated by thousands of cell objects	Constant $O(1)$ memory footprint in GAS
Query Latency (1M Rows)	Timeout / Crash (> 6 min)	15–60+ seconds (or Timeout)	1.2 – 2.0 seconds

[!NOTE]
Boundary Condition on Base Latency: For microscopic datasets (e.g., 5–10 rows in a blank sheet), local SpreadsheetApp cell reads execute in approximately 50–100 milliseconds, whereas the BigQuery API requires a baseline overhead of approximately 0.8–1.5 seconds for job creation, IAM evaluation, and SQL compilation. However, as dataset size scales into enterprise lakehouse dimensions (tens of thousands to hundreds of millions of records), spreadsheet-native scans degrade exponentially ($O(N)$), while IcebergApp maintains a flat, near-constant 1–2 second execution profile.

The Scalability Wall: Google Sheets CRUD Latency vs. IcebergApp

Figure 4: Comprehensive comparison of core CRUD operations between standalone Google Sheets and IcebergApp.

Google Sheets is the world's most intuitive and collaborative frontline data interface. However, as summarized in Figure 4, developers attempting to utilize Google Sheets as an analytical data store or high-volume operational backend inevitably confront four fatal bottlenecks:

Capacity & Quotas (10-Million Cell Ceiling): Google Sheets enforces a hard limit of 10 million cells per workbook. High-frequency IoT telemetry, audit logs, and enterprise transaction streams quickly exhaust this quota, causing workbook corruption, sluggish loads, and script terminations. In contrast, IcebergApp backs Workspace with infinite, petabyte-scale Parquet storage on Google Cloud Storage.
Search & Query Latency (V8 Memory Overload): Querying records in large sheets requires pulling ranges into the Apps Script V8 runtime using getDataRange().getValues(). Serializing hundreds of thousands of cells across Google's internal RPC layer saturates script memory (triggering V8 heap exhaustion) and frequently triggers the 6-minute execution timeout before data processing even begins. IcebergApp overcomes this by pushing query filters directly into Iceberg metadata, achieving 1–2 second retrieval times regardless of table size.
Insert & Append Latency (Calculation Freeze): Adding batches of rows with appendRow() or setValues() forces Google Sheets' calculation engine to recalculate formula trees across the entire workbook, re-evaluate conditional formatting rules, and serialize cell revision histories, creating multi-second freezes. With IcebergApp, table.insertValues() streams records directly into Parquet files with zero client-side recalculation overhead.
Update & Delete Latency (The Critical Pain Point): Updating scattered records requires searching the entire grid in memory, modifying values, and rewriting massive 2D arrays back to the sheet. Worse, deleting rows matching specific criteria using SpreadsheetApp.deleteRow(i) in a loop is notoriously catastrophic: each deletion shifts rows upward, recalculates row coordinates, and triggers an independent API payload. Deleting merely 100 rows can easily freeze the script for minutes or cause runtime timeouts. IcebergApp replaces this with atomic ACID DML updates and deletions that execute on storage metadata in seconds.

How IcebergApp Resolves the Crisis

IcebergApp fundamentally resolves this crisis by adhering to the Separation of Presentation and Storage:

Google Sheets as an Agile, Ephemeral View: Google Sheets is retained exclusively as a lightweight, human-friendly 2D viewing and input surface (holding only current micro-batches or aggregated query results).
Zero-Latency Appends (table.insertValues): Incoming rows staged on a sheet are flushed directly into Iceberg Parquet files on Cloud Storage via atomic ACID commits in 1–2 seconds. The sheet is instantly cleared, maintaining permanent $O(1)$ grid performance.
Sub-Second Search with Predicate Pushdown (table.getValues): Filter queries evaluate column Min/Max statistics within Iceberg metadata manifests. BigQuery skips irrelevant data files, returning only filtered rows to Apps Script in seconds without scanning the entire dataset.
In-Place ACID Mutation & Instant Deletion (table.update & table.deleteRows): Instead of row-by-row iteration in Apps Script, updates and deletions are dispatched as distributed SQL DML executed directly on Iceberg metadata and data files. Deleting millions of archived rows is completed atomically in seconds, permanently banishing deleteRow() loops.

Usage

1. Prerequisites and Environment Binding

To use IcebergApp, your script project must be linked to a Google Cloud Platform (GCP) project that has the BigQuery API and Google Cloud Storage JSON API enabled.

In the Apps Script editor:

Add the BigQuery API (v2) under Services.
Enable the appsscript.json manifest file in Project Settings.
Include the required OAuth scopes for BigQuery, Google Sheets, Drive (for temporary test spreadsheet management), Cloud Storage (for ephemeral bucket life-cycling), and external requests:

{
  "timeZone": "Asia/Tokyo",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "BigQuery",
        "serviceId": "bigquery",
        "version": "v2"
      }
    ]
  },
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/bigquery",
    "https://www.googleapis.com/auth/spreadsheets",
    "https://www.googleapis.com/auth/drive",
    "https://www.googleapis.com/auth/devstorage.read_write",
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

Add the src/IcebergApp.js library file from the IcebergApp GitHub repository directly to your project, or add it as a library.

2. Initializing and Creating an Iceberg Table

You initialize the client by referencing your project ID, catalog name (BigQuery dataset), and region location:

const PROJECT_ID = "your-gcp-project-id";
const CATALOG_NAME = "lakehouse_catalog";
const REGION = "asia-northeast1"; // Crucial: Align BigQuery and GCS region

const app = IcebergApp.openByCatalog(PROJECT_ID, CATALOG_NAME, REGION);

const schema = [
  { name: "id", type: "INT64", mode: "REQUIRED" },
  { name: "device_name", type: "STRING" },
  { name: "temperature", type: "FLOAT64" },
  { name: "status", type: "STRING" },
  { name: "recorded_at", type: "TIMESTAMP" },
];

const table = app.create("IoTMetrics", {
  schema: schema,
  storageUri: "gs://your-lakehouse-bucket/tables/IoTMetrics",
  partitionBy: ["DATE(recorded_at)"],
  clusterBy: ["id"],
});

3. Bidirectional Data Ingestion

IcebergApp treats Google Sheets 2D arrays as first-class citizens. You can append tabular data directly into an Iceberg table without converting types manually:

const sheetValues = [
  ["id", "device_name", "temperature", "status", "recorded_at"],
  [1001, "Sensor_Alpha", 24.8, "NORMAL", new Date()],
  [1002, "Sensor_Beta", 89.2, "CRITICAL", new Date()],
  [1003, "Sensor_Gamma", 21.5, "NORMAL", new Date()],
];

// Appends records atomically via ACID transaction
const insertedCount = table.insertValues(sheetValues);
console.log(`Inserted ${insertedCount} rows.`);

4. Querying with Predicate Pushdown and Direct Sheet Export

When retrieving records, IcebergApp allows you to project columns and define filter conditions. Because these filters are pushed down to Iceberg's metadata manifests, execution completes in seconds even over massive datasets:

// Query only matching rows
const rows = table.getValues({
  columns: ["device_name", "temperature"],
  where: "status = 'CRITICAL'",
});

console.log(rows);
// Output: [["device_name", "temperature"], ["Sensor_Beta", "89.2"]]

// Or stream the filtered result set directly into a Google Spreadsheet
const ss = SpreadsheetApp.create("IoT_Critical_Alerts");
const sheet = ss.getSheets()[0];

table.exportToSheet(sheet, "A1", {
  where: "status = 'CRITICAL'",
});

console.log(`Exported alerts to: ${ss.getUrl()}`);

5. In-Place Row Mutation and Deletion

IcebergApp supports ACID-compliant modifications directly against Cloud Storage without full table rewrites:

// Atomically update row attributes
const updateResult = table.update("status = 'RESOLVED'", "id = 1002");
console.log(updateResult);

// Atomically delete rows satisfying a condition
const deleteResult = table.deleteRows("status = 'ARCHIVED'");
console.log(deleteResult);

6. Snapshot Isolation and Time Travel

Because Iceberg records changes as immutable state transitions, you can query historical data without creating database backups:

// Query table state as it existed 15 minutes ago
const pastTime = new Date(Date.now() - 15 * 60 * 1000);
const pastRecords = table.asOf(pastTime).getValues({
  where: "id = 1002",
});

console.log(pastRecords);
table.resetSnapshot(); // Reset state back to HEAD

Testing: 5 GAS-Centric Practical Scenarios

Testing a data lakehouse connector inside Google Apps Script requires validating high-concurrency storage operations against Workspace runtime constraints. The test.js script in the IcebergApp repository implements a Pure Lifecycle Architecture that dynamically provisions necessary cloud resources and executes end-to-end tests before purging all created entities.

Below are 5 practical testing scenarios demonstrating how IcebergApp addresses real-world challenges unique to Google Apps Script. (Note: Running this automated lifecycle test suite requires configuring your appsscript.json with all 5 OAuth scopes detailed in the Prerequisites section: BigQuery, Spreadsheets, Drive, Cloud Storage devstorage.read_write, and script.external_request.)

Scenario 1: Zero-Residue Infrastructure Life-Cycling

Figure 5: Automated test lifecycle implemented in test.js. Transient cloud resources are dynamically provisioned on demand and guaranteed to be purged in a finally block.

In serverless development, automated continuous integration (CI) tests frequently leave behind orphaned cloud resources—temporary BigQuery datasets, abandoned Cloud Storage buckets, and stray Google Spreadsheets. Over time, these orphaned artifacts accumulate cloud billing costs, consume project quotas, and clutter production namespaces.

Figure 5 details how IcebergApp eliminates cloud clutter through a deterministic, three-phase Pure Lifecycle Architecture:

Dynamic Ephemeral Provisioning (Left Panel): Before executing assertions, test.js dynamically provisions an isolated BigQuery dataset (lakehouse_test_[timestamp]) and a uniquely tagged Google Cloud Storage bucket (gs://lakehouse-iceberg-test-[project-id]-[timestamp]).
Autonomous End-to-End Execution (Center Panel): The suite constructs an Iceberg table, inserts 2D arrays, validates Predicate Pushdown, verifies snapshot time-travel queries, performs atomic DML mutations, and exports results into a newly created Google Spreadsheet.
Guaranteed Absolute Teardown (Right Panel): Wrapped in a robust try...finally block, the test suite guarantees that regardless of test outcome (pass or fail), all created entities—the Iceberg table, the temporary Google Spreadsheet, the ephemeral BigQuery dataset, and the GCS bucket—are completely dropped and destroyed, restoring the GCP and Workspace environments to a pristine zero-residue state in under 25 seconds:

00:00:00  Info    🚀 Starting IcebergApp Automated Test Suite (Stage 3/4 Protocol 17 Compliance)
00:00:00  Info    --- STEP 0-A: Ensuring Isolated Dataset [lakehouse_test_[test-run-id]] ---
00:00:01  Info    ⚡ Dataset [lakehouse_test_[test-run-id]] absent. Provisioning at [asia-northeast1]...
00:00:03  Info    ✅ Dataset [lakehouse_test_[test-run-id]] created at [asia-northeast1].
...
00:00:20  Info    --- ABSOLUTE CLEANUP: Purging ephemeral test resources ---
00:00:20  Info    🗑️ Dropped Iceberg table: Test_Iceberg_[test-run-id]
00:00:21  Info    🗑️ Trashed temporary Spreadsheet: [spreadsheet-id]
00:00:22  Info    🗑️ Removed Ephemeral BigQuery Dataset: [lakehouse_test_[test-run-id]]
00:00:24  Info    🗑️ Deleted Ephemeral GCS Bucket: gs://lakehouse-iceberg-test-[project-id]-[test-run-id]
00:00:24  Info    ✨ CLEANUP COMPLETED: Workspace restored to pure state.

Scenario 2: High-Volume Spreadsheet Data Ingestion (The 10-Million Cell Ceiling)

Figure 6: Micro-batch streaming pipeline. Google Sheets serves as an ephemeral ingestion buffer, flushing rows into Iceberg Parquet storage and resetting to maintain permanent O(1) responsiveness.

Google Sheets enforces a hard ceiling of 10 million cells per workbook. For enterprise applications ingesting continuous sensor feeds, POS terminal transaction logs, or high-volume Google Forms submissions, this quota is reached quickly, resulting in sheet locking, browser crashes, and automation failure.

As illustrated in Figure 6, IcebergApp redefines Google Sheets as a high-throughput Transient Ingestion Buffer:

Transient Buffer Staging (Left Panel): Incoming operational data is temporarily recorded into an active Google Sheet. Because the sheet is never used as long-term storage, cell counts stay well below the 10-million limit.
Atomic Micro-Batch Streaming (Center Panel): A time-driven Apps Script trigger or event hook reads the range using sheet.getDataRange().getValues() and flushes the entire 2D array directly into Iceberg Parquet files on Cloud Storage using table.insertValues(sheetValues). The data is committed via an atomic ACID transaction in 1–2 seconds without calculating sheet formulas or inflating workbook size.
Instant Grid Reset (Right Panel): Upon successful commit, the script clears the active sheet range. The spreadsheet immediately resets to row zero, maintaining permanent $O(1)$ UI responsiveness, while analytical data accumulates limitlessly across petabytes of durable Iceberg storage.

Scenario 3: Predicate Pushdown over BigQuery Quotas

Figure 7: Predicate pushdown evaluation mechanics. BigQuery inspects Iceberg Avro manifests to prune unneeded files before scanning storage.

When Google Apps Script developers query external data stored in flat files (like raw CSV or JSON on Cloud Storage), query engines must scan every single byte from beginning to end. Over millions of rows, this full-table scan consumes significant BigQuery query analysis quotas, drives up cloud costs, and frequently triggers Apps Script's 6-minute execution timeout.

Figure 7 visualizes how IcebergApp and BigQuery eliminate this bottleneck through Predicate Pushdown and Metadata Pruning:

Filter Query Submission: An Apps Script function issues a targeted query, such as table.getValues({ where: "price > 1000.0" }).
Metadata Evaluation: BigQuery evaluates the query filter against Iceberg’s Avro manifest files. The manifest stores precomputed minimum and maximum values (min_price, max_price) for every physical Parquet file.
Physical File Pruning: Files whose max_price is below 1000.0 are flagged as skipped (costing zero bytes of physical data scan). BigQuery only reads the byte ranges of the matching Parquet files from Cloud Storage, completing the query in approximately 1.2 seconds and returning the structured result back to Apps Script:

00:00:07  Info    --- STEP 3: Querying with Predicate Pushdown ---
00:00:08  Info    Result (Headers + Rows): [["id","product","price"],["101","Quantum Sensor Alpha","1500.0"],["102","Superconducting Coil","3200.5"]]

Scenario 4: In-Place Record Mutation (ACID Updates)

Figure 8: In-place record mutation contrast. Traditional data lakes require full-file rewrites, whereas IcebergApp performs atomic ACID updates directly on metadata and storage.

Traditional data lakes built on raw Cloud Storage objects are fundamentally immutable: individual rows cannot be updated in place. If an Apps Script automation needs to deduct inventory stock or update an order approval flag, developers were traditionally forced to download the entire multi-gigabyte Parquet or CSV file into memory, update the row in code, and re-upload the entire file. This process causes extreme network latency, risks concurrent write conflicts, and easily exceeds GAS memory limits.

Figure 8 contrasts this broken legacy workflow with IcebergApp's atomic in-place mutation:

Legacy Approach (Left Panel): Multi-step download, in-memory mutation, and complete dataset overwrite—resulting in severe lock contention, dirty reads, and minutes of execution time.
IcebergApp Atomic DML (Right Panel): Calling table.update("stock = stock - 2", "id = 101") delegates the mutation directly to BigQuery, which applies the modification at the storage tier using Iceberg ACID transaction semantics. Positional or equality delete manifests and updated data slices are committed instantaneously, guaranteeing immediate read-after-write consistency without full-table rewrites:

// Atomically deduct stock directly on storage
table.update("stock = stock - 2", "id = 101");

The test confirms the update succeeds in place in under two seconds without data corruption or lock conflicts.

Scenario 5: Point-in-Time Data Recovery (Time Travel Audit)

Figure 9: Snapshot timeline and time-travel query mechanism. Developers can query previous table states (Snapshot 2) even after faulty overwrites (Snapshot 3) without restoring database backups.

Human error in spreadsheet operations is inevitable. Accidental formula overwrites, faulty batch updates, or automated script glitches can overwrite critical business rows. Recovering past data in traditional databases requires restoring monolithic database backups—a slow, expensive process that takes hours and halts production.

Figure 9 illustrates how IcebergApp leverages Iceberg’s native Snapshot Isolation to achieve instant time-travel audits:

Immutable Snapshot Timeline: Every write operation (INSERT, UPDATE, DELETE) creates an immutable snapshot milestone along a chronological timeline (Snapshot 1 at $t_0$, Snapshot 2 at $t_1$, Snapshot 3 at $t_2$).
Accidental Corruption Simulation: When a faulty update or unintended overwrite occurs at $t_2$, the previous states remain fully intact on Cloud Storage.
Sub-Second Historical Query (asOf): By invoking table.asOf(pastTime).getValues({ where: "id = 1002" }), Apps Script reaches back along the timeline to retrieve the exact table state as it existed at $t_1$. Historical ground truth is restored into Google Sheets in seconds without database downtime or backup recovery:

00:00:08  Info    --- STEP 4: Verifying Snapshot Isolation (asOf) ---
00:00:12  Info    --- STEP 5: DML Update ---
00:00:14  Info    ✅ Table Test_Iceberg_[test-run-id] successfully updated.
00:00:15  Info    --- STEP 5-B: Executing Time Travel Query ---
00:00:15  Info    ✅ Time travel snapshot verified successfully.

Future Horizons: Advanced Enterprise Applications

Figure 10: Five strategic enterprise horizons unlocked by unifying Google Workspace with Apache Iceberg lakehouses.

The ability to control Apache Iceberg natively from Google Apps Script introduces transformative possibilities for modern enterprise data architecture. As visually mapped out across the five connected strategic application nodes of Figure 10, uniting the world's most accessible collaborative frontend (Google Workspace) with the open, high-performance analytical storage of Apache Iceberg unlocks five high-impact architectural horizons:

1. IoT & Edge Telemetry Ingestion: The "Infinite Sheet" Architecture (Node 1)

Frontline operations frequently encounter Google Sheets' strict 10-million cell limit when collecting continuous data from factory sensors, field logistics, smart meter endpoints, or high-volume Google Forms submissions.

With IcebergApp, Google Sheets evolves into a real-time ingestion buffer. Edge events and sensor pulses captured via Google Forms or Webhook web apps are staged in a transient operational sheet. A lightweight, time-driven Apps Script trigger flushes these micro-batches directly into Iceberg Parquet tables via table.insertValues(values) and safely clears the active grid. The data immediately enters enterprise cold storage with automated daily partitioning, eliminating cell quota limitations while providing frontline staff with instantaneous query access to historical aggregations.

2. Time-Travel Financial & Audit Governance: Immutable Enterprise Ledgers (Node 2)

Corporate financial reporting and supply chain logistics operate under demanding regulatory scrutiny (e.g., Sarbanes-Oxley Act [SOX], SEC Rule 17a-4, and IFRS). Traditional spreadsheet-centric tracking suffers from unintentional overwrites, unrecorded macro mutations, and missing point-in-time audit trails.

IcebergApp solves this governance gap through Iceberg's native snapshot isolation. Because every INSERT, UPDATE, and DELETE creates a deterministic, immutable snapshot in Cloud Storage, developers can construct automated compliance inspectors. Internal audit teams can inspect ledger states from the previous quarter, fiscal year-end, or preceding second simply by invoking table.asOf(auditTimestamp).exportToSheet(sheet). Point-in-time state recovery occurs without restoring monolithic database backups, transforming Workspace into an audit-proof financial control center.

3. Generative AI & Multimodal Vector Lakehouse Integration (Node 3)

As enterprises deploy Large Language Models (LLMs) like Google Gemini and Vertex AI into their daily productivity workflows, ensuring AI agents access live, authoritative organizational ground truth is critical.

IcebergApp establishes a serverless data pipeline connecting Workspace directly to enterprise AI platforms. Operational records accumulated in Apache Iceberg can be embedded into vector stores or queried directly by Gemini via BigQuery ML and BigLake integrations. An Apps Script trigger can query the lakehouse, invoke Gemini multimodal models with contextual enterprise data, and generate synthesized analytical executive briefs directly into Google Docs or formatted KPI dashboards in Google Sheets—entirely serverless and without manual data exports.

4. Multi-Engine Open Federation: Zero Vendor Lock-In (Node 4)

The defining strength of Apache Iceberg is its complete independence from proprietary compute engines. When data is committed via IcebergApp, it is stored as open-standard Apache Parquet files and Avro metadata trees directly in customer-owned Google Cloud Storage buckets.

This eliminates vendor lock-in. Data ingested from a simple Google Form via Apps Script is immediately readable and writable by Apache Spark, Trino, Snowflake, Databricks, and BigQuery concurrently, with zero ETL translation and zero data duplication. Data engineers can perform heavy machine learning model training in Spark while business analysts interact with the exact same live dataset through Google Sheets in real time.

5. Agentic AI Orchestration via Model Context Protocol (MCP) & GASADK (Node 5)

The convergence of autonomous Generative AI agents and open lakehouse storage reaches its full operational potential when mediated by standardized tool-calling interfaces. The Model Context Protocol (MCP) has rapidly established itself as the open industry standard for connecting AI foundation models to external data sources and execution engines.

By combining IcebergApp with GASADK (Agent Development Kit for Google Apps Script), developers can seamlessly expose IcebergApp's lakehouse operations as deterministic MCP tool endpoints hosted directly inside Google Apps Script:

Autonomous Analytical Tool Calling: AI agents powered by Google Gemini (running across Gemini CLI, Google Antigravity, Claude Desktop, Cursor, or enterprise sidecars) can dynamically discover and execute IcebergApp methods such as queryIceberg, insertValues, updateRecords, and timeTravelAudit via standard MCP RPC.
Natural Language to Optimized Lakehouse DML: Business users can instruct Gemini in plain natural language (e.g., "Analyze sales anomalies across our APAC IoT sensor metrics, prune irrelevant partitions, and adjust the flagged calibration offsets"). Gemini formulates the query, pushes down metadata filters through IcebergApp, reasons over the returned 2D array payload, and issues atomic ACID DML updates without human SQL intervention.
Closed-Loop Workspace Automation: When anomalies or business milestones are identified, the Gemini agent can simultaneously update the Iceberg lakehouse, append audit logs into a Google Spreadsheet, trigger automated Gmail alerts, and generate a synthesized executive summary in Google Docs—creating a fully autonomous, serverless enterprise data loop.

Summary

This article introduced IcebergApp, an open-source Google Apps Script library that seamlessly unifies Google Workspace with enterprise Apache Iceberg lakehouses on Google Cloud. By decoupling presentation from storage and orchestrating BigQuery as a serverless distributed query accelerator, IcebergApp permanently eliminates Google Sheets cell limits and CRUD latency, enabling developers to query, mutate, and manage petabyte-scale datasets directly from Apps Script.

Key architectural takeaways from this article:

Bridging Workspace Automation and Enterprise Lakehouses: Connects familiar Google Sheets and Apps Script workflows directly to open Apache Iceberg storage on Google Cloud without dedicated middleware, virtual machines, or JDBC proxies.
Eliminating GAS Timeouts and Memory Constraints: Uses BigQuery to evaluate Iceberg metadata trees via Predicate Pushdown and Columnar Projection, maintaining a constant $O(1)$ memory footprint in Apps Script and returning filtered queries in 1–2 seconds.
Overcoming the Google Sheets Scalability Ceiling: Bypasses the 10-million cell limit and resolves crippling latency across search, append, update, and row deletion by delegating heavy mutations to serverless Lakehouse storage while using Sheets as a transient ingestion buffer.
Enterprise ACID Transactions and Snapshot Time Travel: Delivers in-place DML updates and instant point-in-time snapshot recovery (table.asOf()), enabling resilient disaster recovery from accidental spreadsheet overwrites without database downtime.
Future-Proof Ecosystem and Agentic AI Orchestration: Unlocks open multi-engine federation (Spark, Trino, Snowflake) without vendor lock-in, and empowers autonomous Google Gemini agents to execute lakehouse workflows via the Model Context Protocol (MCP) and GASADK.

For complete source code, installation steps, and implementation details, visit the IcebergApp GitHub Repository.

Hearing the Mountain's Roar: How Antigravity CLI's AI Agents & IoT Data Track Volcanic Shockwaves

Tanaike — Wed, 02 Sep 2026 01:29:20 +0000

Turning 29k home weather stations and Gemini AI agents into a 15-minute volcanic warning shield

Published Paper: Capturing Volcanic Lamb Waves and Blast Yields with Netatmo Weather Networks (ESS Open Archive)

Abstract

Explosive volcanic eruptions generate powerful atmospheric Lamb waves—acoustic-gravity waves trapped in the planetary boundary layer that travel horizontally across the globe at sound speed. Operating on a continuous background ingest where Google Apps Script (GAS) logs 20-minute weather records to Google Drive, we mapped two benchmark historical eruptions: the 2018 phreatic blast at Mt. Kusatsu-Shirane and the 2018 magmatic explosion at Mt. Shinmoedake. We framed these events within first-principles continuum mechanics inside the Antigravity CLI environment powered by Gemini and the autonomous R&D framework tanaike-lab. Across 29,334 authentic Netatmo observation records in Japan, our framework reconstructs temperature-dependent shockwave velocities (304.38 m/s in sub-zero winter air and 313.27 m/s in mild spring conditions, matching theoretical sound speeds within 98.5% precision), localizes unmonitored volcanic crater azimuths to within 1.78 degrees, quantifies explosive yields (178.8 to 1,041.1 tons of TNT equivalent), and delivers 2.5 to 15 minutes of advance early warning with 100% false alarm elimination (0.0% False Positive Rate) during violent storm baselines. These findings demonstrate how grounding generative AI in first-principles physics yields robust planetary sensing systems.

1. Introduction

Conventional volcanic monitoring infrastructures (such as specialized infrasound microphones and seismographs operated by government agencies and global nuclear monitoring treaties) operate under a severe spatial limitation: observation stations are separated by 100 to 500 kilometers. This extreme spatial sparsity creates massive blind zones, suffers from severe spatial aliasing, and leaves isolated sensors vulnerable to wind turbulence.

To overcome the spatial aliasing of sparse government arrays, we turn to crowdsourced consumer IoT barometers. By treating thousands of residential Netatmo stations across Japan as a continent-scale acoustic antenna (totaling 29,334 authentic observation records), we demonstrate that balcony-mounted pressure sensors can provide 2.5 to 15 minutes of advance warning before volcanic shockwaves and ash strike downstream urban centers.

This research project advanced through an integrated, four-stage research workflow: combining background cloud archiving in Google Drive via Google Apps Script, historical event mapping across past volcanic eruptions, deductive physical theory construction, and Gemini AI multi-agent pattern mining inside the Antigravity CLI terminal environment guided by the AI Co-Researcher framework tanaike-lab.

【Academic Note】: The physical models, data interpretations, inferences, and precursor warning conclusions presented in this paper represent one of many academic perspectives and methodologies regarding volcanic infrasound and atmospheric wave dynamics within the broad geophysics community. Given the inherent complexity of volcanic processes, these findings contribute a novel framework to the ongoing scientific discourse, inviting further empirical validation and community dialogue.

In this article, written for AI practitioners, software architects, and technology leaders, we explore how human-AI collaboration on Antigravity CLI turned ultra-dense IoT sensor data into a proactive planetary defense platform.

2. The Automated Big-Data Pipeline & Research Project Workflow

Figure 1: Executive Infographic of the Volcanic-Lamb-IoT Framework illustrating an explosive volcanic eruption generating 2D cylindrical Lamb waves traveling horizontally along the Earth's surface at 1,134 km/h (speed of sound), intercepted by thousands of residential IoT home weather stations across urban centers, and processed in real time by cloud analytics to compute blast yield in Tons of TNT and deliver a 2.5 to 15-minute early warning countdown.

The operational foundation of this research rests on a continuous, fully automated cloud ingestion system running in the background.

Using Google Apps Script (GAS), an automated serverless cron trigger executes every 20 minutes, calling the Netatmo Connect API to fetch multi-parametric meteorological records (Barometric Pressure, Outdoor Temperature, and Relative Humidity) from hundreds of residential IoT stations distributed across Japanese metropolitan areas and mountain foothills. These incoming data streams are continuously indexed, structured, and archived directly into a centralized Google Drive repository.

Figure 2: Automated IoT Big-Data Pipeline and Volcanic Research Project Workflow on Antigravity CLI showing: (1) Automated Cloud Ingestion via Google Apps Script (GAS) every 20 minutes into Google Drive; (2) Historical Event Mapping extracting 24-hour observation windows (+/- 12 hours) across past volcanic eruptions; (3) Human Physical Theory & Logic Guidance injecting thermodynamic and wave mechanics constraints; and (4) Antigravity CLI Powered by Gemini AI where the tanaike-lab multi-agent matrix executes in a terminal CLI workspace to discover hidden precursor patterns and compute shockwave velocities with 0.0% false alarms.

Under this continuous data accumulation setup, our research project advanced through a structured 4-stage workflow:

Step 1: Automated Live Ingestion: Google Apps Script operates as an autonomous background ingest engine, polling the Netatmo API every 20 minutes to maintain an uninterrupted, longitudinal meteorological archive in Google Drive.
Step 2: Historical Event Mapping: We mapped past historical volcanic eruptions against this vast archive, extracting targeted 24-hour observation windows (from 12 hours before onset to 12 hours after: $T_0 - 12\text{ h} \to T_0 + 12\text{ h}$) for both the 2018 Mt. Kusatsu-Shirane steam blast and the 2018 Mt. Shinmoedake magmatic eruption, as well as baseline calm and stormy control days.
Step 3: Pre- and Post-Eruption Physical Anomaly Investigation: By analyzing atmospheric time series before and after the blasts, we investigated whether subtle hydrothermal degassing anomalies emerge prior to rupture and how explosive atmospheric shockwaves propagate across urban centers after eruption.
Step 4: Theoretical Modeling & Validation on Antigravity CLI: We constructed unified mathematical models (Bolton enthalpy, 2D compressible Lamb wave equations, slowness beamforming, and cylindrical energy flux integration) and supplied them to Gemini AI running inside Antigravity CLI to verify that volcanic early warnings and crater diagnostics operate with zero false alarms.

3. Accessible Atmospheric Physics: 4 Intuitive Everyday Analogies

How does an uncalibrated $150 weather gadget on an apartment balcony capture a volcanic explosion hundreds of kilometers away? The underlying physics can be understood through four intuitive real-world analogies:

Figure 3: Understanding Volcanic Shockwaves: 4 Intuitive Everyday Analogies. Panel 1 shows Lightning vs. Thunder (lightspeed cloud data outrunning 1,134 km/h sound waves to give early warning). Panel 2 shows Ripples in a Pond (2D cylindrical wave trapping along the Earth's surface). Panel 3 shows 150km Binaural Hearing (home weather sensors working like ears to pinpoint crater azimuth). Panel 4 shows the Speed Gate & Chorus Test (filtering out messy wind turbulence).

1. "Lightning vs. Thunder" — The Race Between Speed of Light and Speed of Sound

When lightning strikes in the distance, you see the brilliant flash instantly, but the rumble of thunder arrives many seconds later. That is because light travels at 300,000 km/s, while sound crawls through the air at roughly 340 m/s.

Our IoT early warning framework exploits this fundamental physical gap. When a volcano erupts, the atmospheric shockwave travels horizontally at acoustic sound speed (approximately 315 m/s, or 18.9 km per minute). Meanwhile, IoT weather stations sitting in the near-field (10 to 30 km from the crater) detect the initial pressure pulse within 30 to 90 seconds and beam their digital telemetry to the cloud at the speed of light.

A perceptive question naturally arises: If individual IoT stations report on 20-minute batch intervals, how is a 2.5 to 15-minute advance lead time operationally possible?

The answer lies in two interlocking physical and network principles:

The Acoustic Travel-Time Horizon Across Distance: Atmospheric shockwaves require finite physical time to propagate across geography. For downstream infrastructure located 50 to 300 km away from the crater, the acoustic travel time creates an unavoidable physical delay: approximately 2.6 minutes for mountain communities at 50 km, 5.3 minutes at 100 km, 9.5 minutes for Tokyo at 180 km (from Mt. Kusatsu-Shirane), and 14.8 minutes (nearly 15 minutes) for the Fukuoka transit corridor at 280 km (from Mt. Shinmoedake). Because near-crater sensors transmit their detections to cloud servers in under a minute, downstream cities receive their alerts well before the physical wave arrives.
Asynchronous Temporal Staggering Across Dense Spatial Clusters: In crowdsourced networks, individual home weather stations do not report in synchronized lockstep; their 20-minute transmission cycles are asynchronously distributed across time. Across a dense regional cluster of 100 stations, an updated packet reaches the cloud every 12 seconds on average ($\Delta t_{ ext{effective}} pprox 1,200 ext{ s} / 100 = 12 ext{ s}$). This dense staggering transforms discrete 20-minute station updates into a continuous, high-frequency spatial tracking stream, while modern edge-triggered webhooks can stream instantaneous sub-second bursts upon detecting steep pressure gradients ($\Delta P / \Delta t$).

2. "Ripples in a Pond" — 2D Cylindrical Wave Trapping

Unconfined atmospheric explosions radiate energy spherically in three dimensions. As the wavefront expands, acoustic energy thins out rapidly, dissipating with the square of the distance ($\propto 1/r^2$).

Volcanic Lamb waves behave differently. Trapped against the Earth's surface by gravity and stratified air density, they propagate as a two-dimensional cylindrical ring. Because acoustic energy cannot escape vertically, the pressure pulse decays much more slowly ($\propto 1/\sqrt{r}$). This acoustic waveguide effect preserves signal integrity across hundreds of kilometers, allowing uncalibrated balcony barometers in downtown Tokyo to record sharp micro-barometric pulses from craters 180 km away.

3. "Binaural Hearing Across 150 Kilometers" — Slowness Beamforming

Humans can close their eyes and instantly point toward where a sound came from because the brain calculates the microsecond difference in arrival time between the left and right ears.

Our system applies this exact principle across an entire region. By measuring millisecond arrival time differences across 25 to 88 IoT stations spaced over a 150-kilometer baseline, the slowness delay-and-sum beamforming algorithm overlays recorded waveforms across all 360 degrees of azimuth. The exact angle where all waveforms constructively reinforce each other pinpoints the volcanic crater with sub-degree accuracy, without requiring prior knowledge of the crater coordinates.

4. "The Speed Gate & The Chorus Test" — Silencing Violent Storm Gusts

A critical instrumentation challenge immediately emerges: local wind turbulence. Under Bernoulli's principle, wind gusts blowing across an open balcony create sharp localized pressure drops. On stormy days, a single station can record hundreds of false pressure spikes.

To eliminate false alarms, tanaike-lab established two physical hurdles:

The Speed Gate: Meteorological wind gusts travel with the weather front at 10 to 25 m/s (36 to 90 km/h), whereas authentic volcanic Lamb waves travel at sound speed (300 to 330 m/s, or ~1,134 km/h). Any signal moving slower than sound is instantly rejected.
The Regional Chorus Test: A wind gust is a localized, uncorrelated event hitting one home at a time. A volcanic shockwave is a massive orchestral wavefront that strikes dozens of homes across an entire prefecture in geometric cadence.

By requiring multi-station phase coherence (Semblance greater than or equal to 0.70), all 378 storm gust spikes recorded during severe gales were filtered out, achieving 100% false alarm elimination (0.0% False Positive Rate).

4. Data Processing Pipeline & The Philosophy of AI Pattern Discovery

Figure 4: Multi-Parametric IoT Data Processing Pipeline showing the 5-step transition from residential weather measurements to planetary intelligence: (1) Raw IoT Weather Ingestion (Pressure, Temp, Humidity), (2) Zero-Phase Waveform Filtering (removing tidal drift), (3) Sound Speed & Temperature Inversion (reconstructing 304-313 m/s velocities), (4) Binaural Beamforming (isolating crater bearing within 1.78 degrees), and (5) Blast Energy & Ash Shadow (computing TNT explosive tons and mapping ash cooling).

The Core Philosophy: Guiding AI's Pattern Discovery with Physical Logic

Generative AI excels at high-dimensional pattern recognition. Yet, when applied blindly to noisy meteorological time series, unconstrained models risk latching onto spurious correlations and generating ungrounded artifacts.

Transforming raw AI output into verifiable scientific discovery requires a hybrid approach: coupling pattern-mining agents directly with first-principles theoretical frameworks and domain logic:

The Guiding Paradigm: When we supply Generative AI not only with raw numbers, but with the exact physical laws, thermodynamic equations, and geometric constraints governing the phenomenon, we provide the AI with a structured cognitive lens. This dramatically magnifies the probability of discovering essential physical patterns while filtering out spurious noise.
A Unified Methodology Across Planetary Disasters: This philosophy is the common intellectual thread uniting all our published disaster prediction breakthroughs:

In Earthquake Prediction (Unified LAIC-AGW Theory), we supplied AI with lithosphere-atmosphere coupling equations and seismic moment tensors to discover pre-seismic radon ionization and thermodynamic enthalpy spikes ($\delta \theta_e = 5.96\text{--}15.47\text{ K}$) hours before fault rupture.

In Urban Torrential Rain Forecasting (LFD-TRP Framework), we supplied AI with 3D Navier-Stokes momentum and thermodynamic helicity equations to capture localized convective initiation 45 minutes in advance.

In Volcanic Early Warning (Volcanic-Lamb-IoT Framework), we supplied AI with 2D compressible Lamb wave equations, Bolton steam enthalpy, and slowness beamforming constraints to isolate volcanic shockwave patterns and crater bearings from 29,334 noisy IoT records.

The 6-Stage Multi-Parametric Pipeline

Driven by this human-guided AI paradigm, our processing pipeline executes an end-to-end derivation:

Pre-Eruption Hydrothermal Enthalpy Tracking: Outdoor temperature, humidity, and barometric pressure are converted into Equivalent Potential Temperature using Bolton's formulation. Subtracting regional baseline trends reveals subtle thermal-steam anomalies (plus 1.5 to 3.2 Kelvin) downwind of the volcano hours before rupture.
Zero-Phase Digital Filtering: Continuous barometric pressure series are conditioned using bidirectional zero-phase Butterworth bandpass filters (0.0005 to 0.02 Hz), removing 24-hour diurnal tidal pressure cycles while preserving exact wave arrival timestamps without phase distortion.
Temperature-Dependent Travel-Time Inversion: Rather than assuming a constant speed of sound, the model performs line-integrals over local temperature fields ($c = \sqrt{\gamma R T}$), accounting for sound speed deceleration across freezing mountain plateaus.
Slowness Delay-and-Sum Beamforming: Waveforms from regional sub-arrays are shifted and stacked across a 360-degree slowness grid to compute semblance coherence, isolating back-azimuth bearings.
Cylindrical Acoustic Energy Flux Integration: Integrating pressure variance over the 2D cylindrical surface and scaling by atmospheric scale height (approximately 8.4 km) quantifies total acoustic energy and converts it to TNT explosive yields.
Volcanic Ash Shadow Cooling Tracking: Dense suburban temperature sensors detect direct solar radiation shielding under drifting ash clouds (causing local temperature drops of minus 4.10 to minus 6.13 degrees Celsius).

5. Empirical Results Across 29,334 Authentic Netatmo Records

Our study validated the Volcanic-Lamb-IoT Framework using 29,334 authentic 20-minute observation records across two major volcanic eruptions and two severe weather control events:

Event & Scenario	Analysis Window ($\pm 12\text{ h}$)	Station Count & Region	Inverted Wave Speed ($c_{\text{app}}$)	Crater Azimuth Error	Acoustic Energy Yield ($E_{\text{acoustic}}$)	Ash Shadow Cooling ($\Delta T$)	False Positive Rate (FPR)
① Mt. Kusatsu-Shirane (Phreatic Blast)	Jan 22 22:00 – Jan 23 22:00 JST	88 stations (Kanto / Chubu)	304.38 $\pm$ 4.73 m/s ($R^2=0.980$)	0.10$^\circ$ ($S_c=0.88$)	7.48 $\times 10^{11}$ J (178.8 t TNT)	$-$6.13 $^\circ$C	0.0% (Detected)
② Mt. Shinmoedake (Magmatic Blast)	Mar 06 02:00 – Mar 07 03:00 JST	59 stations (Kyushu / Fukuoka)	313.27 $\pm$ 4.20 m/s ($R^2=0.990$)	1.78$^\circ$ ($S_c=0.90$)	4.36 $\times 10^{12}$ J (1,041.1 t TNT)	$-$4.10 $^\circ$C	0.0% (Detected)
③ Winter Quiet Baseline (Control 1)	Jan 15 00:00 – Jan 15 23:59 JST	229 stations (Tokyo & Kyushu)	No coherent wave detected	N/A	Background noise	N/A	0.0% (Zero Alert)
④ Spring Storm Baseline (Control 2)	Mar 01 00:00 – Mar 01 23:59 JST	146 stations (Tokyo & Kyushu)	Non-coherent wind turbulence	N/A	Background noise	N/A	0.0% (Zero Alert)

Figure 5: Empirical Breakthroughs: Freezing Steam Blast vs. Magmatic Blast. Panel A illustrates Mt. Kusatsu-Shirane's phreatic explosion generating 304 m/s shockwaves in sub-zero winter air (-5 deg C) with 178 Tons of TNT energy. Panel B illustrates Mt. Shinmoedake's magmatic explosion generating 313 m/s shockwaves in 12 deg C spring air with 1,041 Tons of TNT energy, while residential IoT beamforming pinpoints the crater bearing within 1.78 degrees.

As shown in Figure 5 and Table 1, our framework achieved decisive empirical breakthroughs:

Resolving Temperature-Dependent Wave Speeds: During the Mt. Kusatsu-Shirane phreatic event, the observed shockwave propagated at $304.38 \pm 4.73\text{ m/s}$. While standard sea-level sound speed is approximately $340\text{ m/s}$, sound slows in cold, dense air according to $c = \sqrt{\gamma R T}$. On that sub-zero January morning ($-5^\circ\text{C}$ across the Gunma highlands), theoretical acoustic velocity drops to $304.8\text{ m/s}$. Our uncalibrated IoT array recovered this local thermal deceleration with 99.8% empirical accuracy ($R^2 = 0.980$).
Pinpointing Unknown Craters from 150 km Away: At Mt. Shinmoedake, beamforming across Kyushu stations localized the crater bearing to 169.49 degrees (true bearing 167.72 degrees), an error of just 1.78 degrees.
Quantifying Steam vs. Magma Blast Yields: Total radiated acoustic energy was 7.48 x 10^11 Joules (178.8 tons TNT equivalent) for the Kusatsu-Shirane steam blast, and 4.36 x 10^12 Joules (1,041.1 tons TNT equivalent) for the Shinmoedake magmatic blast—demonstrating that magmatic explosions release roughly 6 times more atmospheric energy than phreatic events.

Figure 6: The Speed Gate and Regional Chorus Test: 100% False Alarm Elimination. Illustrates the dual-filtering mechanics: (1) The Speed Gate rejects slow 10-25 m/s wind gusts while accepting 300-330 m/s volcanic shockwaves, and (2) The Regional Chorus Test filters out isolated single-house wind noise while verifying coherent multi-station wavefronts (Semblance > 0.70), guaranteeing zero false alarms.

As illustrated in Figure 6, the Popperian falsification audit across 15,000+ control records and 378 storm gust spikes confirmed a 0.0% false positive rate, verifying that the network avoids false alarms during severe atmospheric disturbances.

6. Actionable Infrastructure Mitigation: 3 Real-World Applications

Transforming residential weather stations into real-time geophysical intelligence unlocks three transformative societal protection capabilities:

Application 1: Aviation Safety & Urban Infrastructure Early Warning

Figure 7: Application 1: Aviation Safety and Urban Infrastructure Protection Network illustrating automated aircraft plume rerouting, subway intake louvers sealing, hospital HEPA filter cycling, and high-speed rail pre-deceleration triggered 2.5 to 15 minutes before shockwave arrival.

Volcanic ash melts inside jet turbine engines (above 1,400 degrees Celsius), turning into liquid glass and causing total engine failure. Our IoT network estimates explosive yield and crater coordinates within seconds, sending immediate alerts to Air Traffic Control (ATC) and Flight Management Systems (FMS) to dynamically reroute aircraft away from ascending plumes. Downwind cities receive a 5 to 15-minute countdown to automatically seal subway ventilation shafts, switch hospital HVAC systems to internal HEPA filtration, and pause outdoor construction.

Application 2: Volcanic Tsunami Early Detection & Metropolitan Shield

Figure 8: Application 2: Volcanic Tsunami Early Detection and Metropolitan Shield illustrating coastal IoT barometers capturing atmospheric shockwaves outrunning deep-sea tsunamis, delivering 15 to 45 minutes of advance coastal evacuation lead time.

When submarine calderas explode or island flanks collapse (e.g., Krakatoa in 1883, Hunga Tonga in 2022), they generate deadly tsunamis. While deep-ocean tsunamis travel at roughly 200 m/s (slowing to 30–50 m/s in shallow coastal waters), atmospheric Lamb waves travel at 315 m/s—outrunning the ocean wave. Coastal IoT barometers detecting the atmospheric shockwave deliver 15 to 45 minutes of advance tsunami evacuation lead time before the physical water arrives, triggering automated seawall gate closures and coastal rail halts.

Application 3: Blind Crater Localization for Dormant & Unmonitored Volcanoes

Figure 9: Application 3: Blind Crater Localization for Dormant Volcanoes illustrating pre-eruption hydrothermal plume back-tracking via adjoint advection-diffusion and post-eruption multi-array cross-bearing triangulation.

The greatest hazard in volcanology is the surprise eruption from dormant mountains or unmonitored flank fissures where no government instruments exist. In our framework:

Pre-Eruption Hydrothermal Tracking: Prior to rupture, escaping steam creates subtle localized equivalent potential temperature anomalies (plus 1.5 to 3.2 Kelvin). Solving the adjoint advection-diffusion equation tracks the plume back to its source, mapping the coordinates of impending hydrothermal degassing days in advance.
Post-Eruption Multi-Array Triangulation: When an uncataloged explosion occurs, independent regional IoT sub-arrays (e.g., Kanto, Nagoya, Kyushu) calculate cross-bearing azimuth lines (within 0.48 degrees error), pinpointing the active crater coordinates to within 840 meters within minutes.

7. Inside the AI Co-Researcher Framework (`tanaike-lab`) on Antigravity CLI

Figure 10: Autonomous Virtual R&D Laboratory Workflow on Antigravity CLI powered by Gemini AI and tanaike-lab. Illustrates the Human PI providing high-level vision and initial research prompts, orchestrating the Data Ingestion Agent (29,334 authentic records), Modeling & Simulation Agent (2D wave mechanics), Automated Code Developer (Python scripts with assertion hooks), Popperian Falsification Agent, and Automated Manuscript Peer Review Panel.

Executing complex continuum mechanics equations, ingesting 29,334 authentic IoT records, running Popperian falsification checks, and preparing publication-ready LaTeX manuscripts was accomplished using Antigravity CLI powered by Gemini and the auxiliary R&D framework tanaike-lab.

1. How the Project Was Started, Executed, and Completed on Antigravity CLI

The end-to-end execution of this research on Antigravity CLI followed a structured, 5-phase lifecycle:

Human Strategic Ignition & Comprehensive Initial Prompting: Rather than initiating the study with an open-ended prompt, the human PI provided Antigravity CLI with a mathematically constrained research charter. This prompt established six non-negotiable architectural requirements: (i) construct a micro-barometric Lamb wave detection framework using citizen-science IoT time series; (ii) require 24-hour observation windows ($\pm 12\text{ h}$) across the 2018 Kusatsu-Shirane and Shinmoedake eruptions, backed by storm baselines to test falsifiability; (iii) apply Bolton's equivalent potential temperature ($\theta_e$) to isolate pre-eruptive hydrothermal heat fluxes; (iv) enforce bidirectional zero-phase bandpass filtering to preserve exact wavefront phase timestamps; (v) invert propagation velocities using spatially varying temperature fields; and (vi) implement slowness delay-and-sum beamforming to calculate crater azimuths and blast yields directly from multi-station arrival differentials.
Autonomous Plan Audit & Mathematical Dry-Runs: Specialized subagents within tanaike-lab (plan_audit_dryrun_agent and theoretical_feasibility_evaluator) audited the research plan, verifying mathematical consistency, validating the 2D cylindrical energy flux integration model, and formulating the temperature path-integral equation to account for mountain topography.
Automated Pipeline Development & Popperian Assertion Hooks: The code development subagent (experiment_code_developer) constructed isolated Python processing pipelines inside the CLI environment. Automated assertion hooks were embedded into every script, ensuring that data ingestion from Google Drive archives via OAuth2, zero-phase bandpass filtering, and slowness beamforming executed with 100% authentic data and zero synthetic mock arrays.
Empirical Analysis & Agent-to-Agent (A2A) Peer Discussions: Specialized auditing subagents (experimental_results_auditor, data_integrity_sentinel, theory_discussion_reviewer) executed A2A discussions across the 29,334 records. They verified the 304.38 m/s freezing mountain sound speed match, evaluated crater back-azimuth accuracy, and confirmed 100% false alarm rejection across the 378 storm gust spikes.
Manuscript Peer Review & Publication Delivery: The 5-axis simulated peer review panel, style_compliance_officer, and typesetting_linter performed pre-submission audits, ensuring 100% 1-to-1 in-text citation matching, compiling complete LaTeX manuscripts, and producing high-resolution, color-universal infographics before final Human PI authorization.

2. Real-Time Self-Crystallization & CLI Auto-Reinstallation Engine

Unlike static agent scripts, tanaike-lab features an active Real-Time Self-Crystallization & CLI Auto-Reinstallation Engine:

Real-Time Directive Capture: Human steering directives and verified execution lessons are captured on the fly during project runs.
SKILL.md Auto-Crystallization: Lessons are written immediately into SKILL.md.
CLI Plugin Auto-Reinstallation: An automated export engine exports and reinstalls the updated skill matrix directly into the local Antigravity CLI plugin directory on the fly, performing instant Git remote sync to keep the framework continuously evolving.

3. Academic and Systemic Positioning: The Human-AI Synergy Model

Within modern technology R&D, tanaike-lab is positioned as a "Human-Centric Dynamic Virtual R&D Laboratory OS":

Positioning Against "AI Slop" vs. Human-AI Synergy: Unsupervised AI generation frequently suffers from hallucinations and superficial text ("AI slop"). tanaike-lab enforces a Human-AI Synergy Model, where the human PI retains strategic direction while AI subagent matrices accelerate logical formulation, code execution, empirical auditing, and multi-axis peer reviews.
Positioning as a Cognitive Friction Eliminator: Traditional scientific workflows consume massive cognitive bandwidth on operational friction—debugging scripts, interpolating non-uniform temporal grids, adjusting graphics for color universal design, and fixing LaTeX compilation errors. tanaike-lab acts as a cognitive accelerator, eliminating operational friction so human researchers can focus on high-level strategic reasoning.
Triple-Domain Architecture: tanaike-lab operates across three interconnected domain pillars: (1) Academic & Natural Sciences (geophysical modeling, computational fluid dynamics, quantum chemistry, and material science), (2) Generative AI & LLM Engineering (prompt architecture, RAG vector retrieval pipelines, Multi-Agent orchestration, token budget compression, and LLM benchmarks), and (3) Google Ecosystem (Google Apps Script libraries, Google Workspace automation for Drive, Sheets, Docs, Gmail, Forms, and Google Cloud/Workspace APIs with quota limit management).

8. Summary

The release of our manuscript Capturing Volcanic Lamb Waves and Blast Yields with Netatmo Weather Networks on ESS Open Archive marks a major advance in volcanology and planetary sensing. By proving that atmospheric Lamb waves and blast energies can be captured using crowdsourced IoT weather networks with 100% false alarm elimination (0.0% False Positive Rate), this research demonstrates how residential weather gadgets can be transformed into a continent-scale early warning shield.

The analytical results, physical interpretations, and conclusions presented in this study represent one of many diverse scientific perspectives and theoretical approaches within the evolving domain of volcanic physics. Continuous empirical validation and open community dialogue remain essential to building upon these findings.

Beyond geophysics, the real-time self-evolving Human-AI synergy framework embodied by tanaike-lab on Antigravity CLI provides a scalable blueprint for AI engineers and researchers across climate adaptation, LLM multi-agent engineering, and enterprise Google API automation. We invite the global geophysics, meteorology, generative AI, and smart-city engineering communities to read the full open-access paper on ESS Open Archive.

Taking Advantage of Gemini Managed Agents with Google Apps Script

Tanaike — Sun, 30 Aug 2026 07:45:24 +0000

Breaking the Limits of GAS with Direct Cloud-to-Cloud Streaming in Persistent Linux Sandboxes

Abstract

While Google Apps Script (GAS) is a powerful tool for Google Workspace automation, platform and computational constraints often limit its ability to handle advanced workloads. Gemini Managed Agents provide remote Linux sandboxes equipped with bash execution. This article introduces an architecture integrating GAS with a Linux sandbox to execute tasks beyond the capabilities of Apps Script alone. By streaming generated artifacts directly from within the Linux sandbox to Google Drive, this approach bypasses API payload limits, eliminates token overhead, and achieves high-throughput cloud automation.

Introduction

Recently, Martin Hawksey published an inspiring article on AppsScriptPulse exploring the potential of Gemini Managed Agents and the Google Workspace CLI within Google Workspace automation. Ref Gemini Managed Agents (part of the Gemini v1beta Interactions and Environments API) allow developers to provision and interact with remote Linux sandbox environments capable of autonomous code execution, shell commands, and package management. Ref

While Google Apps Script (GAS) is widely used for automating Google Workspace workflows, it operates as a lightweight, restricted serverless runtime without OS-level access, inherently preventing developers from executing various advanced computational workloads. Common platform bottlenecks include restricted low-level network and protocol controls, the absence of headless browser environments for dynamic web rendering, the inability to run native binaries for media transcoding or signal processing, the lack of modern compilers and build toolchains, and strict platform quotas on execution duration and payload sizes. The objective of this article is to introduce a generalized architecture that bridges GAS with a full-featured Linux sandbox provisioned by Gemini Managed Agents, demonstrating how developers can seamlessly offload otherwise impossible workloads to a dedicated cloud compute environment with high throughput and complete autonomy.

By integrating Google Apps Script with Gemini Managed Agents, GAS gains access to a dedicated Linux container (4 vCPU, 16 GB RAM) featuring Python 3.12, Node.js 22, and standard Linux package managers (apt, npm, pip). In this article, I present an end-to-end architecture and client library that enables GAS to orchestrate complex tasks inside a persistent Linux sandbox, eliminating local processing overhead by streaming generated artifacts directly to Google Drive via the ggsrun CLI tool.

Architectural Paradigm: Why Direct Cloud-to-Cloud Streaming?

When generating large files (such as high-resolution screenshots, audio waveforms, or bundled JavaScript) inside a Managed Agent sandbox and transferring them to Google Drive, returning raw binary data as Base64 strings through the Gemini API response to GAS introduces severe platform bottlenecks:

GAS URL Fetch Response Limit: Google Apps Script enforces a strict 50 MB response payload limit on UrlFetchApp. Ref
Code Execution Output Buffer Truncation: The Gemini Interactions API code execution environment imposes standard output (stdout) buffer limits, truncating multi-megabyte Base64 payloads mid-stream. Ref
Rate Limits and Conversational Token Inflation: Gemini Managed Agents enforce a 200,000 Tokens Per Minute (TPM) quota. Ref Base64 encoding inflates binary size by ~33%. In multi-turn sessions, accumulating previous Base64 output strings in conversation history rapidly exhausts input token quotas, triggering immediate 429 Quota Exceeded errors.
CPU and Memory Overhead on GAS: Decoding multi-megabyte Base64 strings and creating Drive blobs inside Apps Script consumes valuable execution time and script memory.

To eliminate these bottlenecks, the optimal approach is to execute the Go CLI tool ggsrun directly inside the Linux sandbox using a dynamically injected OAuth access token (ScriptApp.getOAuthToken()). This allows the sandbox to stream binary artifacts directly to Google Drive over Google Cloud's internal backbone network at speeds exceeding 2 MB/s, completely bypassing Apps Script memory, API response size limits, and token quota exhaustion.

Drastic Input Token Savings via Bi-directional Streaming

The advantages of direct cloud-to-cloud streaming extend far beyond outbound artifact uploads. When bringing large external datasets (high-resolution images, audio, video files, multi-gigabyte CSV/JSON datasets, or machine learning models) into the sandbox for processing, direct inbound downloads provide an equally critical advantage.

Embedding large binary or structured datasets directly into API prompts as Base64 strings or serialized text rapidly consumes input token quotas, instantly hitting the 200,000 Tokens Per Minute (TPM) limit and triggering immediate 429 Quota Exceeded errors. In contrast, by streaming files directly from Google Drive into the sandbox via ggsrun, the prompt requires only a concise instruction (e.g., "Download target dataset from Drive and analyze it"). This architecture reduces input token consumption to virtually zero, completely preventing rate-limit exhaustion.

Process Cost Reduction via Shared Persistent Sandboxes

Furthermore, sharing a single persistent Linux sandbox (environmentId) across multiple clients—including Google Apps Script, local Node.js workstations, Python scripts, and CI/CD pipelines—dramatically lowers operational process costs.

By staging common master datasets, corpora, libraries, or pre-trained models inside the persistent sandbox filesystem (/workspace/), any client can immediately leverage those shared assets to generate content and execute complex processing. This eliminates the redundant overhead of uploading or re-initializing datasets on every execution turn, significantly reducing execution latency, network bandwidth, and cumulative API overhead.

Furthermore, provisioning a single persistent Linux sandbox and sharing its unique environmentId across multiple script executions, Google Apps Script projects, and local developer workstations eliminates redundant initialization overhead and allows multiple tasks to reuse shared working files and pre-installed packages seamlessly.

Workflow

The following diagram illustrates the complete end-to-end architecture where Google Apps Script and local Node.js workstations orchestrate a single persistent Linux sandbox using a shared environmentId, leveraging bi-directional streaming (Inbound download / Outbound upload) and shared master datasets for instant content generation.

Figure 2 Narrative: The diagram outlines the data integration and execution pipelines across cloud and local environments:

Multi-Client Orchestration: Cloud-based Google Apps Script (synchronous trigger, dynamic OAuth token) and local Node.js workstations (real-time SSE streaming, gcloud CLI auth) orchestrate the exact same remote container via a shared environmentId.
Shared Data Repository & Pre-installed Toolchains: The persistent sandbox (4 vCPU / 16 GB RAM) retains shared master datasets and build tools (Playwright, FFmpeg, esbuild), enabling instant content generation without redundant data re-upload overhead.
Inbound Direct Download (ggsrun download): Streams large external datasets directly from Google Drive into the sandbox, eliminating prompt data embedding and preserving input token quotas (200k TPM safe).
Outbound Direct Upload (ggsrun upload): Streams generated binary deliverables directly to Google Drive at 2+ MB/s, completely bypassing GAS 50 MB payload limits and stdout buffer truncation.

Repository

All source code, GAS classes, Node.js stream clients, test suites, and raw execution logs are available in the GitHub repository:

GitHub Repository: tanaikech/managed-agents-gas

Usage

1. Obtain Gemini API Key

Generate an API key from Google AI Studio. Ref This API key authenticates requests to the Gemini v1beta Interactions and Environments APIs.

2. Create Google Apps Script Project

Create a Google Apps Script project using either of the following methods: Ref

Standalone Project: Visit script.google.com and click New project.
Container-bound Project: Open a Google Sheet, Doc, or Form, click Extensions, and select Apps Script.

3. Deploy Client Scripts & Set Script Properties

Copy the following files from the repository into your Apps Script editor:

ManagedAgentSandboxClient.js: Core client class managing sandbox lifecycle, dynamic environment variables, session persistence in PropertiesService, and intelligent 429 rate-limit backoff.
tests.js: Master test suite covering sandbox provisioning, tooling verification, media processing, web scraping, and performance benchmarks.

Navigate to Project Settings > Script Properties and add your API key: Ref

Property: GEMINI_API_KEY
Value: Your Gemini API Key

4. Required Authorization Scopes

Ensure your project manifest (appsscript.json) includes the necessary OAuth scopes:

https://www.googleapis.com/auth/script.external_request: Required for UrlFetchApp API communication.
https://www.googleapis.com/auth/drive: Required for creating destination folders and uploading artifacts. (If using existing folders without DriveApp.createFolder(), https://www.googleapis.com/auth/drive.file can be used).

Testing on Cloud (Google Apps Script)

Execution logs for all tests can be verified in gas-src/execution-logs.md.

1. Provisioning a Unified Linux Sandbox

Executing provisionSharedSandbox() initializes a new remote Linux container, installs all required CLI utilities and dependencies, configures destination Google Drive paths, and saves the resulting environmentId in PropertiesService.

Figure 3 Narrative: The infographic details the 4-step provisioning pipeline. In Step 1, Google Drive creates destination directory ManagedAgent_Artifacts_YYYYMMDD. In Step 2, a 4 vCPU / 16 GB RAM Linux container bootstraps ggsrun, ffmpeg, sox, jq, typescript, esbuild, and Playwright (Chromium). In Step 3, the sandbox validates installed binaries and emits a READY status. In Step 4, the unique environmentId is persisted under SHARED_SANDBOX_SESSION in PropertiesService for multi-test and cross-client reuse.

Step 1: Destination folder ManagedAgent_Artifacts_YYYYMMDD is created in Google Drive.
Step 2: An initialization prompt dispatches commands to download ggsrun, install ffmpeg, sox, jq, typescript, esbuild, and configure headless Chromium via Playwright.
Step 3: The sandbox validates tool installations and returns a READY status.
Step 4: The persistent environmentId is stored under SHARED_SANDBOX_SESSION in PropertiesService for subsequent test reuse.

Running testListSandboxes() queries the Environments API to confirm active sandbox status and metadata.

2. Test 1: User-Agent Customization & POSIX Socket Verification (`runTest1_UserAgentComparison`)

This test demonstrates that while GAS UrlFetchApp automatically overwrites custom HTTP User-Agent headers with Google's proxy identity string, the Managed Agent sandbox preserves arbitrary header configurations via raw POSIX sockets and native curl.

Figure 4 Narrative: The diagram illustrates the request and response paths when sending a custom User-Agent: sample user agent header to httpbin.org/anything. In Google Apps Script (left), platform proxy policies enforce header substitution (❌). In contrast, the Linux sandbox using curl (right) retains the exact custom header string via raw POSIX socket transmission (✅). An autonomous inline Python script compares the reflected JSON payloads and outputs the verification matrix.

Step 1: GAS sends an HTTP GET request to https://httpbin.org/anything specifying User-Agent: sample user agent.
Step 2: The sandbox executes an identical curl request to the same endpoint and compares the reflected JSON payloads using an inline Python script.
Summary of Execution: The comparison confirms that GAS replaced the header with Mozilla/5.0 (compatible; Google-Apps-Script; beanserver; ...), whereas the Linux sandbox preserved the exact sample user agent header string.

3. Test 2: `ggsrun` Deployment & Drive Direct Access Verification (`runTest2_GgsrunDirectDeployment`)

This test validates Google Drive authentication and direct access via ggsrun inside the sandbox by dynamically injecting a fresh OAuth access token (ScriptApp.getOAuthToken()) into the execution turn.

Figure 5 Narrative: The infographic outlines the three execution steps of dynamic authentication and CLI offloading. In Step 1, GAS extracts ScriptApp.getOAuthToken() and dynamically injects it into the execution turn's GGSRUN_AT environment variable (eliminating 1-hour token expiration risks). In Step 2, the sandbox generates a verification file and uploads it via ggsrun upload. In Step 3, ggsrun searchfiles executes a folder query, confirming all 9 artifacts in 12.1 seconds.

Step 1: A verification file 00_ggsrun_verification.txt is created inside /workspace/test2/.
Step 2: ggsrun upload uploads the file directly to the designated Google Drive folder using non-blocking overwrite mode (--nc --cm OverwriteIfNewer -j).
Step 3: ggsrun searchfiles queries the destination folder to confirm file existence and returns structured metadata.
Summary of Execution: The file was created, uploaded, and verified in Google Drive in 12.1 seconds, confirming full workspace interoperability without persisting sensitive access tokens across sessions.

4. Test 3: Playwright Headless Scraping to Direct Drive Upload (`runTest3_PlaywrightDirectUpload`)

This test executes an automated headless Chromium browser session to scrape dynamic JavaScript content and capture multi-viewport screenshots.

Figure 6 Narrative: The diagram depicts headless Chromium (Playwright) rendering dynamic JavaScript pages within the sandbox to capture multi-viewport screenshots (Desktop 1280x800: 92.5 KB, Mobile 375x812: 51.6 KB, Paginated Page 2: 171.9 KB) alongside structured quote JSON (4.1 KB), totaling ~320 KB across 4 artifacts. Bypassing Base64 API conversion, all files are streamed directly to Google Drive via ggsrun upload in a single command, completing in 20.4 seconds.

Step 1: A Node.js Playwright script navigates to a JavaScript-rendered quote website (quotes.toscrape.com/js/).
Step 2: Playwright captures full-page Desktop (1280x800) and Mobile iPhone emulation (375x812) screenshots of Page 1.
Step 3: Playwright clicks pagination controls, captures a Desktop screenshot of Page 2, and extracts structured quote data into 02_Page2_Quotes.json.
Step 4: ggsrun upload transfers all 3 PNG images and the JSON dataset directly to Google Drive in a single command.
Summary of Execution: All 4 artifacts (totaling ~320 KB) were generated and uploaded in 20.4 seconds, successfully rendering client-side JavaScript that GAS cannot parse natively.

5. Test 4: FFmpeg Audio Synthesis & Transcoding to Direct Drive Upload (`runTest4_FFmpegAudioDirectUpload`)

This test executes native digital signal processing inside the sandbox using FFmpeg and SoX to synthesize multi-tone audio chords.

Figure 7 Narrative: The infographic illustrates the digital signal processing (DSP) pipeline inside the Linux sandbox. Three sine wave generators (440 Hz / A4, 554.37 Hz / C#5, 659.25 Hz / E5) are combined through the ffmpeg amix filter complex into a 3-second harmonic major chord MP3 (73.4 KB), while ffprobe extracts stream metadata into JSON (1.8 KB). Both binary audio and JSON analysis are streamed directly to Google Drive via ggsrun in 9.1 seconds.

Step 1: ffmpeg synthesizes a 3-second harmonic major chord MP3 by combining three sine waves (440 Hz, 554.37 Hz, and 659.25 Hz) through an amix audio filter complex.
Step 2: ffprobe analyzes the output stream and extracts waveform metadata into 03_Audio_Analysis.json.
Step 3: ggsrun upload uploads 03_Chord_Major.mp3 (73.4 KB) and 03_Audio_Analysis.json (1.8 KB) directly to Google Drive.
Summary of Execution: High-fidelity audio synthesis, metadata extraction, and Drive upload completed in 9.1 seconds.

6. Test 5: TypeScript AST Extraction & `esbuild` Bundling to Direct Drive Upload (`runTest5_TypeScriptASTDirectUpload`)

This test demonstrates modern JavaScript/TypeScript build tooling inside the sandbox environment.

Figure 8 Narrative: The diagram outlines the dual build toolchains operating on TypeScript source code (matrix.ts). The first branch employs the official TypeScript Compiler API to parse the Abstract Syntax Tree (AST) and export interface schemas (04_TypeScript_AST.json: 152 B). The second branch leverages esbuild to compile a standalone IIFE bundle (04_Matrix_Bundle.iife.js: 1.2 KB) in just 13 milliseconds. Both deliverables are offloaded to Google Drive via ggsrun in 10.0 seconds.

Step 1: A TypeScript module (matrix.ts) defining generic classes and interfaces is written to /workspace/test5/.
Step 2: A Node.js script utilizes the official TypeScript Compiler API to parse the AST and export interface and method schemas into 04_TypeScript_AST.json.
Step 3: esbuild bundles and minifies matrix.ts into a standalone IIFE JavaScript bundle (04_Matrix_Bundle.iife.js).
Step 4: ggsrun upload transfers both the AST schema and the bundled JavaScript to Google Drive.
Summary of Execution: AST parsing, bundle compilation (13 ms build time), and Drive upload completed in 10.0 seconds.

7. Test 6: Performance Benchmark: Direct `ggsrun` Upload vs. Base64 via GAS (`runTest6_DriveUploadPerformanceComparison`)

This benchmark evaluates transferring a binary payload (10,000 bytes) from the sandbox to Google Drive across two distinct methods:

Figure 9 Narrative: The benchmark infographic compares Approach A (direct ggsrun streaming) against Approach B (Base64 transfer via API -> GAS decode). Approach A finished in 16.20 seconds (0.60 KB/s, zero GAS CPU usage), proving to be 1.98x faster than Approach B (32.13 seconds, 0.30 KB/s, 1.23 s GAS CPU). Approach A completely eliminates Base64 payload inflation (~33%) and prevents multi-turn conversational token exhaustion.

Approach A (Direct ggsrun Upload): The sandbox generates a 10 KB binary file from /dev/urandom and streams it directly to Google Drive via ggsrun in a single interaction turn (freshInteraction: true).
Approach B (Base64 Transfer via API -> GAS Blob Save): The sandbox encodes the 10 KB binary into Base64, returns it through the Gemini API response text, and GAS decodes the string and saves the file to Drive.

================================================================================
PERFORMANCE BENCHMARK REPORT: 10,000 BYTES FILE TRANSFER TO GOOGLE DRIVE
================================================================================
| Metric                       | Approach A: Direct ggsrun Upload | Approach B: Base64 via Gemini API -> GAS |
| :--------------------------- | :------------------------------- | :--------------------------------------- |
| Transfer Method              | Direct Sandbox-to-Drive (Go CLI) | Base64 Stream -> GAS -> Drive            |
| Drive File Name              | benchmark_10kb_ggsrun.bin        | benchmark_10kb_gas.bin                   |
| Verified File Size           | 10,000 bytes (9.77 KB)           | 10,000 bytes (9.77 KB)                   |
| API Turns Required           | 1 Turn (Direct Offload)          | 1 Turn (Base64 Retrieval)                |
| Local GAS Processing Time    | 0.00 s (Zero CPU overhead)       | 1.23 s (Base64 Decode & Blob Creation)   |
| Total End-to-End Duration    | 16.20 s                          | 32.13 s                                  |
| Effective Throughput         | 0.60 KB/s                        | 0.30 KB/s                                |
| Performance Multiplier       | 1.98x FASTER                     | Baseline (Higher Latency & Token Usage)  |
================================================================================

Summary of Benchmark Findings: Direct streaming via ggsrun was 1.98x faster, eliminated 100% of Apps Script CPU/memory decoding overhead, and prevented conversational token quota consumption. For multi-megabyte payloads, this direct streaming architecture is essential to prevent 429 Quota Exceeded errors.

Testing on Local Workstations (Node.js Stream Runner)

To demonstrate cross-platform interoperability enabling developers to control the exact same persistent Linux sandbox from both Google Apps Script and local workstations, a high-performance Node.js client powered by Server-Sent Events (SSE) streaming was implemented. Ref

1. Purpose and Advantages of the Local Stream Runner

While Google Apps Script operates under a synchronous blocking execution model where agent events are aggregated at the end of the HTTP request, the local Node.js runner (built with the @google/genai SDK) provides significant developer benefits:

Real-Time Lifecycle Visibility (SSE Streaming): Streams internal reasoning steps (thought), executed shell commands (code_execution_call), sandbox standard output/error (code_execution_result), and model text (model_output) live to the terminal with ANSI color coding.
Interactive Hybrid Development Workflow: Enables developers to prototype, debug, and calibrate agent prompts and toolchains locally with real-time feedback before deploying them into automated, hands-off Google Apps Script triggers.
Zero-Friction Sandbox Sharing (GAS ↔ Local): By simply setting ENVIRONMENT_ID in a local .env file to the identifier generated during Apps Script provisioning, the local client immediately attaches to the existing container, sharing all pre-installed packages, compiled binaries, and workspace files without re-installation overhead.
Automated OAuth Token Integration: Dynamically extracts fresh Google OAuth access tokens via the Google Cloud SDK (gcloud auth print-access-token) and injects them into GGSRUN_AT, executing direct-to-Drive file uploads identically to Apps Script without manual credential copying.

2. Local Setup and Test Execution

Local test suites can be executed through the following straightforward steps:

Step 1: Clone the repository and install dependencies by running npm install inside the local-node.js-src directory.
Step 2: Copy .env.example to .env and specify GEMINI_API_KEY, the persistent ENVIRONMENT_ID, and the destination TARGET_FOLDER_ID.
Step 3: Run npm test (or individual tests npm run test:1 through test:6) to monitor agent execution in real-time.
Step 4: When testing is complete, run npm run test:teardown to safely purge the remote sandbox environment and release cloud resources.

Full raw execution transcripts with live streaming outputs can be reviewed in local-node.js-src/execution-logs.md, confirming 100% functional parity with Google Apps Script executions.

Appendix: Gemini Managed Agents API Usage Patterns

The following patterns summarize common interaction models when working with the Gemini v1beta Interactions and Environments API:

Base Endpoint

POST https://generativelanguage.googleapis.com/v1beta/interactions?key=${API_KEY}
Content-Type: application/json

Scenario 1: Sharing a Single Persistent Sandbox Across Multiple Clients

Provision a remote environment once by setting environment.type to "remote". Save the returned environment_id and pass it as a string in subsequent requests across any client (GAS, Node.js, Python, or CI/CD).

{
  "agent": "antigravity-preview-05-2026",
  "input": "Run task in shared container...",
  "environment": "environments/env-12345"
}

Scenario 2: Using Isolated Sandboxes per Execution

Set environment.type to "remote" on every call when tasks require a completely fresh, isolated Linux environment.

{
  "agent": "antigravity-preview-05-2026",
  "input": "Execute client-specific isolated task...",
  "environment": {
    "type": "remote"
  }
}

Scenario 3: Preserving Multi-turn Conversational Context

Include previous_interaction_id when the agent must retain knowledge of prior reasoning, variables, or command outputs.

{
  "agent": "antigravity-preview-05-2026",
  "input": "Based on the previous output, proceed to step 2...",
  "environment": "environments/env-12345",
  "previous_interaction_id": "interaction-prev-67890"
}

Scenario 4: Reusing Sandbox with Fresh Context (`freshInteraction`)

Specify the existing environment_id and omit previous_interaction_id. This preserves all files and installed tools on the Linux container while resetting conversation history to zero tokens, preventing TPM rate-limit exhaustion.

{
  "agent": "antigravity-preview-05-2026",
  "input": "Execute a completely new task in the existing sandbox...",
  "environment": "environments/env-12345"
}

Summary Matrix

Summary

This article introduced an enterprise-grade architecture integrating Google Apps Script with Gemini Managed Agents (Linux sandboxes) to fundamentally transcend traditional serverless runtime constraints. By combining persistent remote sandboxes with bi-directional direct cloud-to-cloud streaming via ggsrun, developers can achieve advanced processing capabilities previously impossible in Apps Script while avoiding API payload limitations and conversational token rate quotas.

Overcame Apps Script Limits: Enabled advanced workloads requiring native Linux environments—such as headless browser scraping (Playwright), audio synthesis (FFmpeg), and TypeScript compilation (esbuild)—directly from Google Apps Script.
Autonomous Fusion of AI Reasoning & Linux Execution: Transcended static external command execution by uniting Gemini's cognitive reasoning with native Linux shell autonomy, enabling dynamic command synthesis, runtime code execution, and autonomous self-correction across complex workflows.
Bi-directional Streaming Token & Payload Optimization: In addition to direct artifact uploads, streaming large input datasets directly from Drive into the sandbox eliminates prompt data embedding and Base64 conversion, minimizing input/output token usage to bypass GAS 50 MB limits and the 200,000 TPM rate quota.
Process Cost Reduction via Shared Sandboxes: Staging and sharing the container filesystem and common master datasets across clients eliminates redundant data re-upload and tooling setup overhead per task, substantially reducing execution latency and bandwidth costs.
Empirically Proven 2x Performance Acceleration & Zero Memory Footprint: Validated through benchmarks that direct cloud-to-cloud CLI streaming is 1.98x faster than traditional API Base64 retrieval while imposing zero CPU decoding load or local memory consumption on Google Apps Script.

Redefining the Role of Google Apps Script in the Era of Generative AI

Tanaike — Fri, 21 Aug 2026 06:41:03 +0000

Abstract

Generative AI and autonomous agents do not obsolete Google Apps Script (GAS); they elevate it into an indispensable deterministic execution substrate. This article establishes an enterprise hybrid architecture dividing responsibilities between AI's probabilistic reasoning (the brain) and GAS's secure, zero-cost, event-driven execution (the nervous system). Through 12 production use cases—spanning MCP servers, deterministic guardrails, and hybrid batching—we formalize four foundational principles for engineering resilient, scalable Google Workspace automations.

Introduction

Google Workspace is a cloud-native groupware suite provided by Google for enterprise organizations, educational institutions, and individuals alike. By seamlessly integrating essential productivity tools—including Gmail, Google Drive, Calendar, Docs, and Sheets—it enables secure real-time collaboration and streamlined workflows worldwide.

For over a decade, the backbone of automation across this ecosystem has been Google Apps Script (GAS). Ref

As a serverless JavaScript runtime, GAS internally encapsulates Google's robust OAuth 2.0 authentication machinery. Developers can orchestrate cross-service workflows spanning Sheets, Docs, Drive, and Gmail with zero infrastructure provisioning, zero credential leakage, and zero server maintenance costs. Furthermore, GAS's integration capabilities extend far beyond Google Workspace; through Advanced Google Services and REST APIs, it seamlessly interfaces with the broader Google APIs ecosystem—including Google Analytics (GA4), BigQuery, YouTube Data API, Google Maps, and Cloud Translation.

The recent exponential surge in Generative AI has brought the Workspace automation paradigm to a historic turning point. Intuitive prompt-based solutions and autonomous agents are emerging that promise end-to-end task execution without traditional coding:

Google Workspace Studio: Intuitive natural-language AI workflow orchestration Ref
Gemini Spark: Autonomous AI agents managing 24/7 background tasks and tool execution Ref
Google Workspace MCP Server and Gemini Integration: Protocol-driven, context-aware autonomous tool invocation Ref

Faced with these capabilities, engineers and IT leaders frequently ask: Has Google Apps Script been made redundant by Generative AI? Is writing script code a thing of the past?

The answer is an unequivocal "No."

In fact, the rise of flexible AI agents has brought the distinct technical advantages and irreplaceable domain of GAS into sharper focus than ever before.

Compared to pure natural-language agents and LLM-centric automations, GAS retains fundamental architectural strengths:

Deterministic Reproducibility, Sub-Second Latency, and Zero Inference Cost GAS eliminates hallucination risks, enforcing strict mathematical rules, financial transactions, and rigid business logic with 100% deterministic precision. It incurs zero token costs and zero model inference latency for pure computational tasks.
True Background Event Triggers and Deep UI Integration (Custom Functions) Through time-driven triggers (cron schedules) and event triggers (form submissions, spreadsheet edits, file uploads), GAS operates completely autonomously in the background without requiring continuous human presence or active browser sessions. Furthermore, features like Spreadsheet Custom Functions execute computational logic directly inside spreadsheet formula cells.
Flexible External API Orchestration via UrlFetchApp With UrlFetchApp, GAS provides fine-grained control over HTTP headers, authentication payloads, and REST methods (GET, POST, PUT, DELETE, PATCH). Through doGet and doPost Web Apps, GAS functions simultaneously as a secure webhook listener and a serverless API gateway.
Enterprise-Grade Governance as a Core Service Google Apps Script has been promoted to a Google Workspace Core Service under General Availability (GA). It inherits enterprise data protection agreements, administrator policy controls, and standard technical support guarantees. Ref
Accelerated Development via Native Gemini in the Script Editor Gemini is now natively integrated into the Apps Script editor sidebar, enabling context-aware code generation, automated refactoring, and inline debugging. Ref This drastically lowers the entry barrier while accelerating delivery for both professional engineers and citizen developers.

Workflow Comparison: Direct Natural-Language Execution vs. Deterministic Script Execution

When comparing direct natural-language Workspace execution (via Google Workspace Studio or Gemini Spark) with the Gemini-assisted Google Apps Script paradigm, distinct workflow topologies emerge:

Approach 1: Direct Natural-Language Workspace Execution (Workspace Studio / Gemini Spark)

User provides natural-language prompt
LLM dynamically interprets prompt, reasons about API execution order, and sequentially calls Google Workspace APIs
System returns output

Approach 2: Script-Fixed Execution (Google Apps Script with Gemini)

User provides natural-language prompt
Gemini synthesizes and verifies Google Apps Script code (e.g., via the built-in Gemini side panel in the Script Editor)
Google Apps Script engine executes the fixed script directly
System returns output

In Approach 1, because the LLM performs probabilistic reasoning on every single execution, subtle interpretation fluctuations can introduce non-deterministic behavior and inference latency overhead.
In Approach 2, because natural-language instructions are compiled once into concrete GAS code, 100% deterministic reproducibility is guaranteed on every subsequent run, barring external network anomalies. Furthermore, because runtime execution bypasses LLM inference entirely, execution latency is dramatically lower than direct natural-language API dispatching. Additionally, human engineers can seamlessly write, inspect, or modify the code directly, preserving full developer control.

The contemporary imperative is not an "AI vs. Code" dichotomy, but the systematic engineering of Hybrid Architectures:

Development Phase: Leveraging generative LLMs to synthesize, lint, and test GAS code at lightning speed.
Runtime Phase: Pairing the unstructured comprehension and reasoning of AI models with the deterministic validation, state persistence, event dispatching, and secure API execution of GAS.

This article delivers an exhaustive guide to the strategic positioning, architectural taxonomy, and 12 highly practical use cases of Google Apps Script in the generative AI era.

Google Apps Script Architecture and Project Design

To architect resilient systems, developers must first master the architectural differences between Standalone Scripts and Container-bound Scripts. These project types differ not only in storage location but also in security boundaries, permission scopes, and lifecycle management.

1. Standalone Scripts

A Standalone Script is an independent project stored directly in Google Drive, decoupled from any specific Workspace document. Ref

Creation: Created via Google Drive: [New] > [More] > [Google Apps Script].
Cross-Service Orchestration: Coordinates data pipelines spanning multiple files, folders, and domains.
Autonomous Cron Automation: Executes scheduled background jobs via time-driven installable triggers.
REST Endpoints & MCP Servers: Hosts serverless Web Apps (doGet / doPost), webhook receivers, and Model Context Protocol (MCP) servers.
Enterprise SaaS Integration: Acts as a secure integration hub connecting platforms like Slack, GitHub, Stripe, and Jira.
Shared Code Libraries: Encapsulates reusable business logic and utility modules across an organization.
Security & Access Control: Because it has no parent document, the script's access permissions are managed independently. Source code, Script Properties, and sensitive credentials remain completely hidden from end users, making it the ideal architecture for background administrative tasks and public API endpoints.

2. Container-bound Scripts

A Container-bound Script is embedded directly within a specific Google Workspace host file (Sheets, Docs, Slides, or Forms). Ref

Creation: Opened from the host file menu: [Extensions] > [Apps Script].
In-Document Data Processing: Executes sheet macros, custom formatting, and batch cell transformations.
Spreadsheet Custom Functions: Defines bespoke calculation formulas callable directly inside spreadsheet cells.
Document UI Extensions: Builds custom menu bars, modal dialogs, and interactive sidebars.
Immediate Local Event Handlers: Responds instantly to user interactions via onEdit, onOpen, and onFormSubmit.
Security & Operational Model: Access permissions are strictly inherited from the parent file. Users with edit access to the document can view and execute the script. The script can bind directly to active document instances (e.g., SpreadsheetApp.getActiveSpreadsheet()) without requiring explicit resource IDs, making it exceptionally convenient for document-centric workflows.

3. Project Type Comparison Matrix

Evaluation Dimension	Standalone Script	Container-bound Script
Primary Use Cases	Web Apps, REST endpoints, MCP servers, cross-file batch jobs, SaaS integration hubs	Custom Functions, sheet macros, document UI extensions (sidebars/menus)
Permission Management	Managed independently per script (optimal for hiding source code and API keys)	Inherited directly from the parent host document
Resource Binding	Explicit ID or URL required (e.g., `SpreadsheetApp.openById(id)`)	Direct contextual access (e.g., `SpreadsheetApp.getActiveSpreadsheet()`)
Public API / Web Apps	Highly recommended (clean separation of concerns for API hosting)	Possible, but tightly coupled to the host document

Diverse Execution Triggers and Modalities in GAS

GAS is far more than a simple macro engine; it is a full-fledged serverless execution runtime with diverse invocation mechanisms:

Script Editor (Manual / Debug Execution): Interactive testing, profiling, and Gemini-assisted code authoring.
Simple & Installable Triggers: Fully autonomous, zero-touch execution triggered by time schedules (cron), form submissions, spreadsheet edits, or calendar events.
Custom Functions: Direct formula-level computation and inference within Google Sheets cells.
Custom Menus & Document Buttons: On-demand interactive macros triggered by end users via sheet buttons or top menu bars.
Sidebars & Modal Dialogs (HTML Service): Embedded interactive web interfaces within Workspace applications for guided human-in-the-loop workflows.
Web Apps (doGet / doPost): Public or organization-restricted REST API endpoints, webhook receivers, and MCP servers.
Google Apps Script API: Remote invocation and deployment from external CI/CD pipelines (GitHub Actions) or local developer tooling (clasp, ggsrun).
Google Workspace Add-ons: Enterprise-wide or global distribution through the Google Workspace Marketplace.

For an exhaustive breakdown of execution mechanisms, see Report: How to Run Google Apps Script.

💡 Configuration Note: Centralized Gemini API Key

In accordance with security best practices, the scripts in this guide retrieve API credentials dynamically via PropertiesService rather than hardcoding keys. Before executing the examples, open the Apps Script editor, navigate to Project Settings > [Script Properties], and add a property named GEMINI_API_KEY containing your valid Gemini API key.

12 Highly Practical Use Cases of Google Apps Script in the AI Era

The following 12 categories detail the definitive, battle-tested roles of GAS in the generative AI landscape, complete with official references, production-ready code samples, architecture diagrams, security analyses, and advanced extension patterns.

1. Deterministic Custom Functions with External API Integration and In-Memory Caching

Figure 1: Deterministic custom function data flow integrating external APIs with CacheService — Illustrates cell input ingestion, sub-millisecond in-memory cache lookup, open API execution via UrlFetchApp on cache miss, and deterministic multi-column spill array propagation.

Technical Overview and Official References

Google Sheets Custom Functions enable developers to define JavaScript functions in Apps Script that can be called directly within spreadsheet cells just like standard functions (SUM, VLOOKUP). They execute custom computational logic, fetch real-time data from external REST APIs via UrlFetchApp, and populate calculations seamlessly across cells.

Official Reference: Custom Functions in Google Sheets

Concrete Example: Fetching Authoritative Country Data with Array Spilling and CacheService

While LLM-powered spreadsheet formulas excel at freeform text generation and fuzzy summarization, they are unsuited for authoritative factual lookups (statistical data, ISO codes, master catalogs) where zero hallucination is required.

As illustrated in Figure 1, the deterministic data flow executes through five coordinated steps:

User enters a custom formula (e.g., =GET_COUNTRY_INFO("US")) in a Google Sheets cell.
GAS checks CacheService to immediately return cached results without consuming network bandwidth if available.
On a cache miss, UrlFetchApp executes a secure HTTPS GET request to the public REST Countries API.
GAS parses and structures the JSON payload into a clean 2D array and stores it in CacheService (6-hour TTL).
The function deterministically spills "Country Name," "Capital," "Region," and "Population" across four adjacent columns.

Production Script

Paste the following script into your container-bound editor. In any spreadsheet cell, enter =GET_COUNTRY_INFO("US") or =GET_COUNTRY_INFO(A2) to dynamically populate four columns without requiring an API key:

/**
 * Custom function to fetch authoritative country metadata by ISO code and spill across 4 columns.
 * @param {string|number} countryCode 2-letter or 3-letter ISO country code (e.g., "US", "JP", "FR", "DE").
 * @return {Array<Array<string|number>>} 2D array: [[Name, Capital, Region, Population]]
 * @customfunction
 */
function GET_COUNTRY_INFO(countryCode) {
  if (!countryCode) return [["", "", "", ""]];

  const code = String(countryCode).trim().toLowerCase();
  const cache = CacheService.getScriptCache();
  const cacheKey = `country_info_${code}`;

  // 1. Retrieve from in-memory cache if available (6-hour TTL)
  const cachedData = cache.get(cacheKey);
  if (cachedData) {
    try {
      return JSON.parse(cachedData);
    } catch (e) {
      cache.remove(cacheKey);
    }
  }

  // 2. Fetch authoritative data from public REST API
  const url = `https://restcountries.com/v3.1/alpha/${encodeURIComponent(code)}`;
  try {
    const response = UrlFetchApp.fetch(url, {
      muteHttpExceptions: true,
      headers: { Accept: "application/json" },
    });

    if (response.getResponseCode() !== 200) {
      return [["Error: Not Found", "-", "-", "-"]];
    }

    const data = JSON.parse(response.getContentText());
    if (!Array.isArray(data) || data.length === 0) {
      return [["Error: Invalid Response", "-", "-", "-"]];
    }

    const country = data[0];
    const name = country.name?.common || "-";
    const capital = country.capital ? country.capital[0] : "-";
    const region = country.region || "-";
    const population = country.population || 0;

    const result = [[name, capital, region, population]];

    // 3. Cache the structured result for 6 hours (21,600 seconds)
    cache.put(cacheKey, JSON.stringify(result), 21600);
    return result;
  } catch (error) {
    return [[`Error: ${error.message}`, "-", "-", "-"]];
  }
}

Key Advantages

100% Deterministic Accuracy: Relies exclusively on authoritative REST APIs, eliminating hallucination risks inherent in LLM-generated facts.
Zero API Cost & Sub-Second Latency: CacheService caches identical queries in memory for up to 6 hours, preventing redundant quota consumption.
Dynamic 2D Array Spilling: Automatically populates multiple adjacent columns from a single cell formula without manual dragging.

Limitations and Operational Considerations

30-Second Execution Limit: Custom functions must return within 30 seconds, or Google Sheets will throw a #ERROR! timeout.
Read-Only Restrictions: Custom functions cannot modify other cells, alter sheet formatting, or invoke services requiring sensitive OAuth write scopes.

Advanced Patterns and Extensions

Financial Master Sync: Fetch real-time foreign exchange rates or stock quotes from financial APIs and spill price, volume, and moving averages.
Postal Code Geocoding: Resolve postal codes to standardized prefecture, city, and street addresses with multi-tier caching.

2. Event-Driven Zero-Touch Autonomous AI Pipelines

Figure 2: Autonomous AI event pipeline triggered by Google Forms submission — Illustrates end-to-end autonomous execution from Form submission (onFormSubmit) to Gemini priority classification, real-time Sheets logging, and automatic Gmail response draft creation.

Technical Overview and Official References

GAS Installable Triggers monitor Workspace state changes—such as Google Forms submissions (onFormSubmit), spreadsheet cell edits (onEdit), time intervals, and Calendar updates—executing background logic with elevated user authorization without requiring manual intervention.

Official Reference: Installable Triggers in Google Apps Script

Concrete Example 1: Form Ingestion, Sentiment & Urgency Classification, and Gmail Draft Synthesis

As shown in Figure 2, the end-to-end autonomous event pipeline operates through five zero-touch stages:

Customer submits an inquiry through a public Google Form.
An installable onFormSubmit trigger automatically wakes up in the background.
GAS dispatches inquiry text via UrlFetchApp to Gemini 3.6 Flash for urgency classification, sentiment analysis, and response drafting.
Structured classification metadata is appended in real time to the centralized Google Sheet.
GmailApp automatically generates a contextual reply draft in the support mailbox or dispatches urgent notifications to team channels.

Production Script 1 (Form Text Ingestion)

/**
 * Installable trigger executed upon Google Forms submission.
 * Extracts inquiry text, classifies urgency via Gemini, and generates a Gmail draft.
 */
function onFormSubmitTrigger(e) {
  if (!e || !e.namedValues) {
    Logger.log("Execution bypassed: Trigger event object (e.namedValues) is undefined.");
    return;
  }

  const userEmail = e.namedValues["Email Address"] ? e.namedValues["Email Address"][0] : "";
  const userName = e.namedValues["Name"] ? e.namedValues["Name"][0] : "Customer";
  const inquiry = e.namedValues["Inquiry Details"] ? e.namedValues["Inquiry Details"][0] : "";

  if (!userEmail || !inquiry) return;

  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  const prompt = `You are a professional enterprise customer support specialist.
Analyze the following customer inquiry, evaluate its urgency, and compose a polite, professional reply.

Output requirements:
Return strictly a valid JSON object matching this schema:
{"urgency": "High" | "Medium" | "Low", "replySubject": "Subject line", "replyBody": "Full email body"}

Customer Name: ${userName}
Inquiry Details:
${inquiry}
`;

  const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=${apiKey}`;
  const response = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify({
      contents: [{ parts: [{ text: prompt }] }],
      generationConfig: { responseMimeType: "application/json" },
    }),
    muteHttpExceptions: true,
  });

  if (response.getResponseCode() !== 200) {
    Logger.log(`Gemini API error: ${response.getContentText()}`);
    return;
  }

  const json = JSON.parse(response.getContentText());
  const aiOutput = JSON.parse(json.candidates[0].content.parts[0].text);

  // Synthesize Gmail draft for human agent review
  const draftBody = `${aiOutput.replyBody}

---
[AI Evaluation: Urgency ${aiOutput.urgency}]`;
  GmailApp.createDraft(userEmail, aiOutput.replySubject, draftBody);

  Logger.log(`Draft synthesized successfully for: ${userEmail} (Urgency: ${aiOutput.urgency})`);
}

Concrete Example 2: Multimodal Invoice Extraction from Gmail PDF Attachments

Expanding beyond plain text, GAS can ingest binary PDF and image attachments from unread emails, convert their raw bytes to Base64, and pass them as inlineData directly to Gemini 3.6 Flash for structured financial extraction and ledger recording.

Production Script 2 (Multimodal Attachment Processing)

/**
 * Autonomous pipeline to scan unread emails for PDF invoices,
 * extract line items via Gemini Multimodal API, and log to Google Sheets.
 */
function processInvoicePdfMultimodal() {
  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  let sheet = ss.getSheetByName("InvoiceLedger");
  if (!sheet) {
    sheet = ss.insertSheet("InvoiceLedger");
    sheet.appendRow(["IssueDate", "Vendor", "InvoiceNumber", "TotalAmount", "Items", "LoggedAt"]);
  }
  const threads = GmailApp.search('label:inbox is:unread has:attachment filename:pdf "Invoice"');

  for (const thread of threads) {
    const messages = thread.getMessages();
    for (const msg of messages) {
      if (!msg.isUnread()) continue;

      const attachments = msg.getAttachments();
      for (const att of attachments) {
        if (att.getContentType() === "application/pdf") {
          // 1. Convert file Blob to Base64 encoding
          const base64Data = Utilities.base64Encode(att.getBytes());

          // 2. Dispatch multimodal payload to Gemini 3.6 Flash
          const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=${apiKey}`;
          const prompt = `Extract all invoice details from this document and return strictly a JSON object:
Keys: invoiceNumber (string), vendor (string), issueDate (YYYY-MM-DD), totalAmount (number), items (array of strings)`;

          const payload = {
            contents: [
              {
                parts: [
                  { text: prompt },
                  {
                    inlineData: {
                      mimeType: "application/pdf",
                      data: base64Data,
                    },
                  },
                ],
              },
            ],
            generationConfig: { responseMimeType: "application/json" },
          };

          const res = UrlFetchApp.fetch(url, {
            method: "post",
            contentType: "application/json",
            payload: JSON.stringify(payload),
            muteHttpExceptions: true,
          });

          if (res.getResponseCode() === 200) {
            const result = JSON.parse(
              JSON.parse(res.getContentText()).candidates[0].content.parts[0].text
            );

            // 3. Record structured metadata directly into the ledger
            sheet.appendRow([
              result.issueDate,
              result.vendor,
              result.invoiceNumber,
              result.totalAmount,
              JSON.stringify(result.items),
              new Date(),
            ]);
          }
        }
      }
      msg.markRead();
    }
  }
}

Key Advantages

Zero-Touch Automation: Operates 24/7 in the cloud without requiring active browser tabs, local daemons, or server hosting.
Multimodal Binary Ingestion: Direct conversion of PDFs and images (Blob ➔ Base64) allows seamless OCR and structured reasoning in a single pass.

Limitations and Operational Considerations

Installable Trigger Authorization: When configuring triggers programmatically, ensure execution scope grants are verified.
File Size Boundaries: UrlFetchApp request payloads are limited to 50 MB, which easily accommodates standard documents but requires chunking for massive media files.

Advanced Patterns and Extensions

Customer Feedback Escalation: Automatically classify Google Form feedback into categories (Bug, Feature Request, Praise), sending immediate Slack alerts to engineering leads for high-priority bugs.
Automated Resume Screening: Parse candidate resumes submitted via Form, extract skills and years of experience via Gemini, and compile structured applicant rankings in Sheets.

3. Serverless Web API Endpoints via Web Apps (`doGet` / `doPost`)

Figure 3: Serverless REST API endpoint architecture powered by GAS Web Apps — Illustrates secure ingestion of external HTTPS requests, Bearer token verification, Gemini background processing, and deterministic JSON response generation via ContentService.

Technical Overview and Official References

By implementing doGet(e) or doPost(e) handlers and deploying a project as a Web App, GAS functions as an enterprise-grade, serverless REST API endpoint. It parses incoming query parameters, headers, and JSON payloads, processes internal Workspace resources, and returns structured ContentService.MimeType.JSON responses.

Official Reference: Web Apps Guide in Google Apps Script

Concrete Example: RESTful Ingestion Gateway for External Microservices and AI Agents

As illustrated in Figure 3, the serverless Web API endpoint architecture operates through four structured steps:

External clients, autonomous agents, or third-party SaaS platforms dispatch HTTPS doGet or doPost requests to the public Web App URL.
GAS intercepts incoming requests, verifying the Bearer token or authorization header to block unauthorized traffic.
Upon validation, the script executes business logic, queries Workspace databases, or triggers Gemini API calls.
GAS packages data into ContentService.createTextOutput with MimeType.JSON, returning deterministic responses with zero server maintenance.

Production Script

/**
 * HTTP POST Handler for GAS Web App.
 * Ingests external JSON payloads, validates bearer tokens, and persists records.
 */
function doPost(e) {
  try {
    if (!e || !e.postData || !e.postData.contents) {
      return createJsonResponse({ status: "error", message: "Empty request payload." }, 400);
    }

    // 1. Validate custom authorization token
    const expectedToken = PropertiesService.getScriptProperties().getProperty("API_AUTH_TOKEN");
    const incomingToken = e.parameter.token;

    if (expectedToken && incomingToken !== expectedToken) {
      return createJsonResponse({ status: "error", message: "Unauthorized access: Invalid token." }, 401);
    }

    // 2. Parse and validate JSON body
    const body = JSON.parse(e.postData.contents);
    const { category, summary, details } = body;

    if (!category || !summary) {
      return createJsonResponse({ status: "error", message: "Missing required fields: category and summary." }, 400);
    }

    // 3. Persist record into spreadsheet database
    const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("IncomingLogs");
    sheet.appendRow([new Date(), category, summary, details || "", "SUCCESS"]);

    return createJsonResponse({
      status: "success",
      message: "Payload logged and processed successfully.",
      timestamp: new Date().toISOString(),
    }, 200);
  } catch (err) {
    return createJsonResponse({ status: "error", message: err.message }, 500);
  }
}

/**
 * Utility helper to construct standard ContentService JSON output
 */
function createJsonResponse(dataObject) {
  return ContentService.createTextOutput(JSON.stringify(dataObject)).setMimeType(
    ContentService.MimeType.JSON
  );
}

Deployment & Verification via `curl`

Deploy via [Deploy] > [New deployment] > [Web app] with access set to "Anyone". Test the endpoint from your local terminal:

curl -L -X POST "https://script.google.com/macros/s/{DEPLOYMENT_ID}/exec?token=YOUR_API_AUTH_TOKEN"   -H "Content-Type: application/json"   -d '{"category":"SecurityAlert","summary":"Unauthorized access attempt detected","details":"IP: 192.168.1.1"}'

(Note: The -L flag is mandatory to follow Google's HTTP 302 authentication redirect).

Key Advantages

Zero Infrastructure Serverless: Provides a permanent HTTPS REST endpoint without provisioning virtual machines, configuring load balancers, or managing SSL certificates.
Native Workspace Bridge: Ingested data is immediately available to Google Sheets, Drive, and BigQuery connectors.

Limitations and Operational Considerations

Concurrent Execution Limits: Standard Google accounts allow up to 30 concurrent Web App executions (Google Workspace accounts allow more), making it ideal for webhook ingestion rather than massive high-frequency streaming.
HTTP 302 Redirection: Clients must be configured to follow redirects (curl -L or standard HTTP client redirect followers).

Advanced Patterns and Extensions

Webhook Ingestion Hub for Stripe / GitHub: Receive payment confirmations or Git push events, summarize commit messages with Gemini, and update project tracking sheets.
Autonomous Agent Tool API: Expose specific business functions (e.g., createCalendarEvent, searchDrive) as REST endpoints for external agent frameworks.

4. Augmenting Autonomous Agents (Gemini Spark, Antigravity CLI) via MCP & A2A Multi-Agent Protocol

Figure 4: Autonomous agent tool execution via GAS Web App and Model Context Protocol (MCP) — Illustrates autonomous agents (Gemini Spark / Antigravity CLI) invoking serverless GAS tools with encapsulated credentials to manipulate Workspace resources.

Technical Overview and Official References

Autonomous agents interact with enterprise environments through emerging open protocols: the Model Context Protocol (MCP) for granular tool invocation and the Agent-to-Agent (A2A) protocol for hierarchical multi-agent collaboration. By deploying MCP and A2A servers directly on Google Apps Script (GAS) Web Apps, organizations transform GAS into an enterprise-grade execution substrate that encapsulates OAuth tokens, manages complex business rules, and exposes deterministic Workspace capabilities to autonomous agents (e.g., Gemini Spark, Gemini CLI, Antigravity CLI).

Crucially, in large-scale enterprise automation, loading dozens of disparate tools directly into a single primary agent causes Tool Space Interference (TSI)—a failure mode where the LLM misinterprets parameters, suffers tool selection degradation, and exhausts context token limits.

Hosting an A2A Server on GAS resolves TSI through Hierarchical Task Delegation: the primary agent (such as the Gemini CLI or an agentic framework) delegates high-level sub-goals (e.g., "Audit last month's financial spreadsheets and compile an executive summary document") to a dedicated GAS subagent. The GAS subagent orchestrates internal Workspace tools within its own isolated execution context, returning only the synthesized, deterministic outcome to the primary agent.

Protocol Connectivity & Future Roadmap Note

Under current specifications, Antigravity CLI and Gemini Spark connect directly to external MCP (Model Context Protocol) servers for tool execution. While direct connection to external A2A servers is not supported at present, this limitation may be resolved in future framework updates as the multi-agent ecosystem matures. Currently, hierarchical subagent delegation via the A2A Protocol is leveraged by the Gemini CLI and custom A2A clients communicating with the GAS A2A Server.

Google Workspace MCP Server Overview: Official Guide
GASADK (Agent Development Kit for GAS): GitHub (Kanshi Tanaike)
ggsrun CLI Repository: GitHub (Kanshi Tanaike)
GoogleApiApp Library: GitHub (Kanshi Tanaike)
gas-fakes Offline Mock Engine: GitHub (Bruce McPherson)
GASADK MCP/A2A Server Samples: GitHub (Kanshi Tanaike)

Concrete Example 1: Gemini Spark & GASADK MCP Server for GA4 Analytics & Gmail Ingestion

As illustrated in Figure 4, the autonomous agent tool-execution architecture operates across four synchronized stages:

Cloud-native agents (Gemini Spark) or local terminal agents (Antigravity CLI) receive high-level natural language goals from users.
Agents dispatch tool-invocation requests to the GAS Web App endpoint (MCP server) via the Model Context Protocol (MCP).
GAS internally encapsulates OAuth 2.0 tokens and API keys, securely manipulating Google Workspace applications (Sheets, Docs, Gmail) and GA4 datasets.
Deterministic results are returned to the agent as clean JSON, ensuring reliable task fulfillment without prompt bloat.

Gemini Spark MCP Architecture

Figure 4-1: Gemini Spark and GASADK MCP Server Architecture — Illustrates cloud-native agent orchestration invoking GAS-hosted tools over JSON-RPC 2.0 to perform GA4 analysis and Gmail monitoring.

Deployment Workflow

Configure Manifest (appsscript.json): Register GASADK, GoogleApiApp, and required Advanced Services (AnalyticsData).
Deploy MCP/A2A Endpoint: Include DeployMcpServer.js and publish as a Web App accessible to "Anyone".
Register in Gemini Spark: Add the Web App URL (https://script.google.com/macros/s/{DEPLOYMENT_ID}/exec?accessKey=sample) as a Custom Extension.
Autonomous Execution: Prompt Gemini Spark naturally: "@gas-mcp Extract yesterday's GA4 bounce rates and generate a summary report in Google Docs."

Concrete Example 2: Antigravity CLI and the 3-Tier Workspace Orchestration Matrix

The Antigravity CLI (agy) provides a Go-based, sub-millisecond local agent runtime. Operating within a local sandbox (--sandbox), it orchestrates Google Workspace across three distinct operational tiers:

3-Tier Orchestration Architecture

Figure 4-2: Antigravity CLI 3-Tier (Local/Hybrid/Cloud) Workspace Orchestration Architecture — Illustrates local dry-run testing with gas-fakes, rapid terminal execution with ggsrun, and long-running cloud task delegation with GASADK.

Execution Flow

Local Tier (Offline Dry-Run): AI-generated logic is executed locally against gas-fakes to verify syntax and types with zero cloud quota cost.
Hybrid Tier (Synchronous CLI Execution): Rapid queries and single-function executions invoke GAS directly from the terminal via ggsrun with immediate stdout feedback.
Cloud Tier (Long-Running Delegation): Massive data processing and scheduled batch tasks are delegated to GASADK running cloud-natively on GAS.

# Example of sandboxed autonomous orchestration via Antigravity CLI
agy --sandbox "Fetch last month's sales sheet via ggsrun, identify outliers, and draft an executive briefing document."

Concrete Example 3: A2A Protocol for Remote GAS Subagent Collaboration

Primary orchestrator agents (such as Gemini CLI or multi-agent frameworks) deploy an A2A Server on GAS to delegate complex document processing tasks to remote specialized subagents (while Antigravity CLI interacts via external MCP servers).

A2A Protocol and TSI Resolution Architecture

Figure 4-3: A2A Protocol and Tool Space Interference (TSI) Resolution Architecture — Illustrates hierarchical task delegation from primary agents to remote GAS subagents, eliminating tool collision and prompt bloating (clarifying protocol differentiation between MCP-enabled tools and A2A subagent delegation).

TSI Elimination and Context Isolation: The primary agent does not need to load dozens of individual Sheet/Doc manipulation tools into its prompt context. Instead, it dispatches a single high-level JSON-RPC 2.0 task to the remote GAS subagent (Workspace Manager Agent).
Serverless Multi-Agent Infrastructure: Hosting A2A communication on GAS Web Apps eliminates the need to provision and maintain 24/7 Node.js or Python backend servers.

Key Advantages

Zero-Infrastructure Multi-Agent & Tool Hosting: Deploy production MCP and A2A servers directly on Google Cloud infrastructure without server provisioning.
Root-Level TSI Resolution: Offloading sub-tasks to remote GAS subagents prevents prompt bloat and tool confusion in primary agents.
Complete Credential Encapsulation: OAuth 2.0 scopes and API secrets remain strictly isolated inside GAS, never exposed to agent prompt contexts.
Natural Language Task Delegation: End-to-end multi-step tasks (reporting, auditing, alerting) are orchestrated autonomously through plain natural language.
Seamless Local-to-Cloud Flexibility: Developers fluidly balance instant terminal execution (ggsrun) with scalable serverless delegation (GASADK).

Limitations and Operational Considerations

6-Minute Execution Limit: Long-running cloud agent executions must complete within the 6-minute window, using trigger continuation patterns for massive datasets.
Concurrent Web App Quotas: Coordinate simultaneous agent calls to respect standard concurrency limits (typically 30 concurrent executions).

Advanced Patterns and Extensions

Natural Language BigQuery Visualizer: Autonomous agents query enterprise datasets via GAS and automatically render interactive charts in Sheets.
Cross-Drive Semantic Research Agent: An agent searches Drive folders via GAS MCP/A2A, compiles cross-document findings, and synthesizes executive briefings.
Autonomous Multi-Calendar Scheduler: Agents coordinate meeting schedules across organizational boundaries with deterministic availability checks.

5. Secure Internal AI Portals via Web Apps + HTML Service & A2UI

Figure 5: Secure enterprise AI portal powered by HTML Service and organizational authentication — Illustrates single sign-on (SSO) protected web UI communicating asynchronously with backend GAS and Gemini via google.script.run.

Technical Overview and Official References

GAS HTML Service allows developers to build full-stack web applications hosted directly inside Google Workspace. By combining frontend HTML/CSS/JS with backend GAS functions via google.script.run, organizations can deliver internal AI tools protected by Google Workspace SSO without managing external authentication providers.

Furthermore, adopting the Agent-to-User Interface (A2UI) paradigm allows AI models to dynamically return UI cards, interactive action buttons, and dynamic input forms rather than static text.

HTML Service Official Guide: Create and Serve HTML
A2UI with Gemini: Bringing A2UI to Google Workspace with Gemini
Task-Driven Agentic Interfaces: Building Interfaces with A2UI
A2UI for Google Apps Script: Architecture Guide

Concrete Example: Enterprise AI Proofreading and Translation Portal

As illustrated in Figure 5, the enterprise AI portal architecture functions through five integrated steps:

Internal employees access the GAS Web App URL via desktop browsers.
Google Workspace Single Sign-On (SSO) automatically enforces organization-level access control, blocking external unauthorized requests.
The HTML Service frontend asynchronously triggers server-side GAS functions using google.script.run.
GAS securely retrieves the Gemini API key from PropertiesService and checks in-memory CacheService to prevent duplicate API billing.
Adhering to the A2UI framework, dynamic UI feedback and action cards render instantly on the client browser.

Full-Stack Implementation

1. Backend Server Script (`Code.gs`)

function doGet() {
  return HtmlService.createHtmlOutputFromFile("Index")
    .setTitle("Corporate AI Proofreading Portal")
    .setXFrameOptionsMode(HtmlService.XFrameOptionsMode.ALLOWALL);
}

/**
 * Server-side AI execution function invoked via google.script.run
 */
function callGeminiProofread(inputText) {
  if (!inputText || !inputText.trim()) {
    throw new Error("Input text cannot be empty.");
  }

  // 1. Check in-memory cache using MD5 hash
  const rawHash = Utilities.computeDigest(
    Utilities.DigestAlgorithm.MD5,
    inputText,
    Utilities.Charset.UTF_8
  );
  const hashKey = rawHash.map((b) => (b < 0 ? b + 256 : b).toString(16).padStart(2, "0")).join("");
  const cacheKey = `proof_${hashKey}`;

  const cached = CacheService.getScriptCache().get(cacheKey);
  if (cached) return cached;

  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=${apiKey}`;
  const prompt = `You are an expert enterprise editor. Proofread and refine the following business text for clarity, grammatical precision, and professional tone. Provide bulleted improvement notes at the end.

Source Text:
${inputText}`;

  const payload = {
    contents: [{ parts: [{ text: prompt }] }],
    generationConfig: { temperature: 0.3 },
  };

  const response = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify(payload),
    muteHttpExceptions: true,
  });

  if (response.getResponseCode() !== 200) {
    throw new Error(`Gemini API Error: ${response.getResponseCode()} - ${response.getContentText()}`);
  }

  const json = JSON.parse(response.getContentText());
  const outputText = json.candidates[0].content.parts[0].text;

  // Cache result for 2 hours (7,200 seconds)
  CacheService.getScriptCache().put(cacheKey, outputText, 7200);
  return outputText;
}

2. Frontend Interface (`Index.html`)

<!DOCTYPE html>
<html>
  <head>
    <base target="_top" />
    <meta charset="utf-8" />
    <style>
      body {
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        background: #f8f9fa;
        padding: 30px;
        color: #202124;
      }
      .card {
        max-width: 800px;
        margin: 0 auto;
        background: #ffffff;
        padding: 30px;
        border-radius: 12px;
        box-shadow: 0 4px 16px rgba(0, 0, 0, 0.08);
      }
      h2 {
        color: #1a73e8;
        margin-top: 0;
      }
      textarea {
        width: 100%;
        height: 180px;
        box-sizing: border-box;
        border: 1px solid #dadce0;
        border-radius: 8px;
        padding: 12px;
        font-size: 14px;
        font-family: inherit;
        resize: vertical;
      }
      button {
        background: #1a73e8;
        color: #fff;
        border: none;
        padding: 12px 24px;
        font-size: 15px;
        font-weight: 500;
        border-radius: 6px;
        cursor: pointer;
        margin-top: 15px;
      }
      button:hover {
        background: #1557b0;
      }
      button:disabled {
        background: #dadce0;
        cursor: not-allowed;
      }
      #output {
        margin-top: 20px;
        padding: 16px;
        background: #e8f0fe;
        border-left: 4px solid #1a73e8;
        border-radius: 4px;
        white-space: pre-wrap;
        display: none;
      }
      .error {
        background: #fce8e6 !important;
        border-left-color: #d93025 !important;
        color: #c5221f;
      }
    </style>
  </head>
  <body>
    <div class="card">
      <h2>✨ Enterprise AI Proofreading Portal</h2>
      <textarea id="inputText" placeholder="Enter text to proofread..."></textarea>
      <button id="submitBtn" onclick="runProofread()">Execute AI Proofreading</button>
      <div id="output"></div>
    </div>
    <script>
      function runProofread() {
        const text = document.getElementById("inputText").value;
        if (!text.trim()) return alert("Please enter text.");
        const btn = document.getElementById("submitBtn");
        const output = document.getElementById("output");
        btn.disabled = true;
        btn.innerText = "Analyzing text...";
        output.style.display = "block";
        output.className = "";
        output.innerText = "Gemini is reviewing your content...";

        google.script.run
          .withSuccessHandler(function (result) {
            output.innerText = result;
            btn.disabled = false;
            btn.innerText = "Execute AI Proofreading";
          })
          .withFailureHandler(function (err) {
            output.className = "error";
            output.innerText = "Error: " + err.message;
            btn.disabled = false;
            btn.innerText = "Execute AI Proofreading";
          })
          .callGeminiProofread(text);
      }
    </script>
  </body>
</html>

Key Advantages

Zero-Infrastructure Organizational SSO: Restrict access to internal Workspace accounts with a single configuration toggle—no Auth0 or Firebase Auth setup required.
A2UI Extensibility: Seamlessly upgrade from static text responses to dynamic adaptive forms and task cards generated on the fly by AI.

Limitations and Operational Considerations

Iframe Sandbox Constraints: HTML Service operates inside an iframe, which limits certain low-level browser APIs.
Initial Load Latency: Initial page loads require 1–2 seconds to establish the Google Workspace authentication wrapper.

Advanced Patterns and Extensions

Adaptive Task Execution Portals via A2UI: AI dynamically generates input forms based on vague user requests, guiding employees step-by-step through complex workflows.
Corporate Policy Q&A Bot: An internal portal that parses PDF manuals stored in Google Drive, providing authoritative answers with exact page citations.

6. Context-Aware AI Assistant Panels via Sidebars and Dialogs

Figure 6: Context-aware AI assistant panel integrated as a Google Docs sidebar — Illustrates bidirectional UI workflow capturing partial document selections, querying Gemini, and streaming proofread text directly back into the editor.

Concrete Example: In-Editor Text Summarization, Proofreading, and Insertion

As shown in Figure 6, the context-aware sidebar workflow executes seamlessly within the document workspace:

User highlights any text passage in Google Docs.
User clicks a pre-configured AI action (Honorific Polish, 3-Line Summary, Business English Translation) in the custom sidebar.
DocumentApp.getSelection() accurately extracts the highlighted text elements, preserving partial selections.
Backend GAS transmits the payload to Gemini 3.6 Flash.
The synthesized text is previewed in the sidebar and directly inserted at the active cursor position upon clicking "Insert into Document".

Production Script (Google Docs In-Editor Assistant)

1. Backend Script (`Code.gs`)

function onOpen() {
  DocumentApp.getUi()
    .createMenu("🤖 AI Assistant")
    .addItem("Open AI Sidebar", "showSidebar")
    .addToUi();
}

function showSidebar() {
  const html = HtmlService.createHtmlOutputFromFile("Sidebar")
    .setTitle("Context AI Editor");
  DocumentApp.getUi().showSidebar(html);
}

/**
 * Extracts selected text, executes prompt instruction, and returns result
 */
function processSelectedText(instruction) {
  const doc = DocumentApp.getActiveDocument();
  const selection = doc.getSelection();
  if (!selection) throw new Error("Please highlight text in the document first.");

  let selectedText = "";
  const elements = selection.getSelectedElements();
  for (const el of elements) {
    const textElement = el.getElement().asText();
    if (el.isPartial()) {
      selectedText += textElement.getText().substring(
        el.getStartOffset(),
        el.getEndOffsetInclusive() + 1
      ) + "
";
    } else {
      selectedText += textElement.getText() + "
";
    }
  }

  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=${apiKey}`;

  const payload = {
    contents: [
      {
        parts: [
          {
            text: `Instruction: ${instruction}

Target Text:
${selectedText}`,
          },
        ],
      },
    ],
  };

  const res = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify(payload),
    muteHttpExceptions: true,
  });

  if (res.getResponseCode() !== 200) {
    throw new Error(`Gemini Error: ${res.getContentText()}`);
  }

  const json = JSON.parse(res.getContentText());
  return json.candidates[0].content.parts[0].text;
}

/**
 * Inserts AI-generated content directly at current cursor position
 */
function insertTextToDoc(textToInsert) {
  const doc = DocumentApp.getActiveDocument();
  const cursor = doc.getCursor();
  if (cursor) {
    cursor.insertText(textToInsert);
  } else {
    doc.getBody().appendParagraph(textToInsert);
  }
}

2. Frontend Interface (`Sidebar.html`)

<!DOCTYPE html>
<html>
  <head>
    <base target="_top" />
    <style>
      body { font-family: Roboto, sans-serif; padding: 12px; font-size: 13px; }
      button { width: 100%; margin-bottom: 8px; padding: 8px; background: #1a73e8; color: #fff; border: none; border-radius: 4px; cursor: pointer; }
      #result { margin-top: 12px; padding: 10px; background: #f1f3f4; border-radius: 4px; white-space: pre-wrap; font-size: 12px; }
      .insert-btn { background: #34a853; display: none; margin-top: 8px; }
    </style>
  </head>
  <body>
    <h3>📝 AI Document Editor</h3>
    <button onclick="executeAction('Summarize in 3 bullet points')">📌 3-Line Summary</button>
    <button onclick="executeAction('Translate into natural business English')">🌐 Translate to English</button>
    <div id="result">Highlight text in the document and click an action above.</div>
    <button class="insert-btn" id="insertBtn" onclick="insertResult()">📥 Insert into Document</button>
    <script>
      let latestResult = "";
      function executeAction(instruction) {
        document.getElementById("result").innerText = "Analyzing highlighted text...";
        google.script.run
          .withSuccessHandler((res) => {
            latestResult = res;
            document.getElementById("result").innerText = res;
            document.getElementById("insertBtn").style.display = "block";
          })
          .withFailureHandler((err) => alert("Error: " + err.message))
          .processSelectedText(instruction);
      }
      function insertResult() {
        if (!latestResult) return;
        google.script.run
          .withSuccessHandler(() => alert("Inserted successfully into document."))
          .insertTextToDoc(latestResult);
      }
    </script>
  </body>
</html>

Key Advantages

Zero Context Switching: Users analyze and revise content directly within their active editing workflow without copying text back and forth to external chat windows.
Standardized Quality across Teams: All team members sharing the file have instant access to identical, pre-configured AI prompts.

Limitations and Operational Considerations

Desktop Browser Exclusivity: Sidebars are supported on desktop web browsers and do not render on mobile Workspace applications.

Advanced Patterns and Extensions

Spreadsheet Categorization Sidebar: Classifies freeform survey responses in selected rows and inserts category tags into adjacent columns.
Slide Speaker Notes Generator: Reads slide text elements and synthesizes natural presentation scripts directly into the Speaker Notes panel.

7. Modern Local Development, CLI Tooling, and Local LLM Integration

Figure 7: Modern local development environment (clasp/VS Code) integrating local LLMs and GAS — Illustrates local TypeScript development, offline testing with gas-fakes, automated CI/CD deployment with clasp, and terminal execution with ggsrun.

Technical Overview and Official References

Integrating Google's official CLI (@google/clasp), the offline mocking engine gas-fakes, and the synchronous execution CLI ggsrun brings professional software engineering practices (VS Code, Git, TypeScript, GitHub Actions) directly to GAS projects.

Command-line Interface using clasp: Official Guide
Google Apps Script API Overview: API Documentation
gas-fakes Repository: GitHub (Bruce McPherson)
ggsrun Repository: GitHub (Kanshi Tanaike)

Concrete Example: `clasp` ✕ `gas-fakes` Automated CI/CD and `ggsrun` Interactive CLI Control

As shown in Figure 7, developers engineer TypeScript code locally and operate across three synchronized development layers:

Local Tier (CI/CD Unit Testing): Fast offline unit tests execute in Node.js via gas-fakes ($0 quota cost).
Deploy Tier (GitHub Actions Push): Merges to main trigger automated deployments via clasp push.
Local CLI Tier (ggsrun Direct Execution): Developers use ggsrun (requiring manual OAuth) from their local terminal to execute cloud GAS functions instantly without browser interaction.

Architecture Overview

Figure 7-1: GitHub Actions CI/CD Pipeline Architecture with gas-fakes and clasp — Illustrates automated push-triggered workflow executing offline unit tests and deploying verified code to GAS cloud environments.

GitHub Actions CI/CD Pipeline (`.github/workflows/deploy.yml`)

name: Deploy Google Apps Script
on:
  push:
    branches: [ main ]

jobs:
  test_and_deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install dependencies & gas-fakes
        run: npm ci

      # 1. Execute fast offline unit tests with gas-fakes
      - name: Run offline unit tests with gas-fakes
        run: npm test

      # 2. Deploy to GAS via clasp
      - name: Deploy to GAS via clasp
        env:
          CLASPRC_JSON: ${{ secrets.CLASPRC_JSON }}
        run: |
          echo "$CLASPRC_JSON" > ~/.clasprc.json
          npx clasp push --force

💡 Operational Note: Separation between ggsrun and clasp

ggsrun is a high-performance Go CLI designed for interactive developer control requiring manual OAuth 2.0 browser authorization. Consequently, headless GitHub Actions CI/CD pipelines rely on gas-fakes and clasp, while ggsrun serves as the developer's direct terminal bridge for rapid post-deployment testing and batch execution.

Key Advantages

Modern Software Engineering Standards: Git branching, TypeScript type safety, instant offline mock testing, and automated GitHub Actions deployments fully integrated.
Direct Terminal Control via ggsrun: Execute and debug cloud GAS functions directly from the terminal without opening the web editor.
On-Premises Data Privacy: Process confidential enterprise data locally with Ollama (Llama 3) and sync only sanitized summaries to Google Workspace via GAS Web Apps.

Limitations and Operational Considerations

Inbound Communication Setup: Pushing from local machines to GAS Web Apps is straightforward; sending requests from GAS back to local environments requires secure tunnels (Cloudflare Tunnel or ngrok).

Advanced Patterns and Extensions

Local Batch Automation via ggsrun: Python or Node.js data processing scripts invoke ggsrun to write aggregated metrics directly into Sheets and Docs.
Confidential Contract Review with Local LLMs: Legal teams analyze proprietary NDAs locally using Ollama and log review status to Sheets via GAS.

8. Deterministic Output Guardrails & Sandboxing for AI Outputs

Figure 8: Multi-layer deterministic validation guardrails inspecting AI outputs — Illustrates 4-tier inspection gates encompassing Gemini responseSchema syntax enforcement, GAS business rule verification, and sandboxed pre-execution validation.

Technical Overview and Official References

While Generative AI provides unmatched flexibility with unstructured text, it carries intrinsic hallucination risks. In the emerging era of Vibe Coding—where developers and business users prompt LLMs to generate and execute code spontaneously on the fly—running unverified AI-generated script logic directly in production Workspace environments poses severe security and data-corruption vulnerabilities.

By combining Gemini's responseSchema (native JSON Schema enforcement) at Layer 1 and GAS JavaScript logic at Layer 2 with sandboxed pre-execution validation (gas-fakes and ggsrun) at Layer 3 via the Model Context Protocol (MCP), developers establish multi-layer defense gates ensuring vibe-coded scripts run safely in isolated sandboxes before ever touching production data.

Official Reference: Gemini API: Structured Outputs
Antigravity CLI Orchestration Framework: Orchestrating Google Workspace with Antigravity CLI
Sandboxing Guide: Exploring Sandboxing for AI-Generated Google Apps Script
Fake-Sandbox Guide: A Fake-Sandbox for Google Apps Script
Schema Enforcement Guide: Taming the Wild Output: Effective Control of Gemini API Response Formats

Concrete Example 1: Schema Enforcement and Deterministic Guardrails for Expense Claims

As illustrated in Figure 8, multi-layer defense guardrails validate structured AI data outputs across sequential stages:

Input Ingestion: Receipt notes or expense claims submitted as unstructured natural language.
Layer 1 (Gemini responseSchema): Native model-level schema enforcement guarantees structural JSON syntax, required fields, and enumerated types.
Layer 2 (GAS Deterministic Validation): JavaScript logic strictly verifies business rules (positive integer amounts, approved expense categories, valid YYYY-MM-DD dates).
Deterministic Storage: Only verified, fully compliant data is committed to production Google Sheets.

Execution Instructions

Open the Apps Script editor attached to your Google Sheet.
Navigate to Project Settings > [Script Properties] and add GEMINI_API_KEY.
Paste the script below into Code.gs.
Select testExecuteAiWithGuardrail from the top function menu and click [Run].
Check the execution log and observe the verified record securely appended to the "ExpenseClaims" sheet.

Production Script (Data Extraction & Validation Implementation)

/**
 * Test function: execute from Apps Script editor with 1 click
 */
function testExecuteAiWithGuardrail() {
  const sampleInput = "Yesterday on 2026-08-20, I paid $35 for an Uber ride to visit a prospective client.";
  const result = executeAiWithGuardrail(sampleInput);
  Logger.log("Guardrail validation succeeded: " + JSON.stringify(result));
}

/**
 * Validates AI output across multiple guardrails and records to Sheets
 * @param {string} userInput Unstructured user expense description
 * @return {object} Verified structured expense record
 */
function executeAiWithGuardrail(userInput) {
  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  if (!apiKey) {
    throw new Error("GEMINI_API_KEY is not set. Configure it in Script Properties.");
  }

  // Layer 1: Native JSON Schema Enforcement via responseSchema
  const responseSchema = {
    type: "OBJECT",
    properties: {
      amount: { type: "INTEGER", description: "Expense amount as a positive integer" },
      category: {
        type: "STRING",
        enum: ["Travel", "Entertainment", "Office Supplies"],
        description: "Standard expense category",
      },
      date: { type: "STRING", description: "Transaction date in YYYY-MM-DD format" },
    },
    required: ["amount", "category", "date"],
  };

  const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=${apiKey}`;
  const res = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify({
      contents: [
        {
          parts: [{ text: `Extract expense details from the following request.
Input: ${userInput}` }],
        },
      ],
      generationConfig: {
        responseMimeType: "application/json",
        responseSchema: responseSchema,
      },
    }),
    muteHttpExceptions: true,
  });

  if (res.getResponseCode() !== 200) {
    throw new Error(`Gemini API Error: ${res.getResponseCode()} - ${res.getContentText()}`);
  }

  const jsonResponse = JSON.parse(res.getContentText());
  const rawJson = jsonResponse?.candidates?.[0]?.content?.parts?.[0]?.text;
  if (!rawJson) throw new Error("No response payload received from AI.");

  let parsed;
  try {
    parsed = JSON.parse(rawJson);
  } catch (e) {
    throw new Error(`JSON Parse Failure: ${e.message}`);
  }

  // Layer 2: Deterministic Business Rule Validation in GAS
  if (typeof parsed.amount !== "number" || parsed.amount <= 0 || !Number.isInteger(parsed.amount)) {
    throw new Error(`Invalid expense amount: ${parsed.amount}`);
  }
  const validCategories = ["Travel", "Entertainment", "Office Supplies"];
  if (!validCategories.includes(parsed.category)) {
    throw new Error(`Invalid expense category: ${parsed.category}`);
  }
  if (!/^\d{4}-\d{2}-\d{2}$/.test(parsed.date) || isNaN(Date.parse(parsed.date))) {
    throw new Error(`Invalid date format: ${parsed.date}`);
  }

  // Persist only clean, fully compliant data to Google Sheets
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  let sheet = ss.getSheetByName("ExpenseClaims");
  if (!sheet) {
    sheet = ss.insertSheet("ExpenseClaims");
    sheet.appendRow(["Date", "Category", "Amount", "LoggedAt"]);
  }
  sheet.appendRow([parsed.date, parsed.category, parsed.amount, new Date()]);

  return parsed;
}

Concrete Example 2: Safe Execution of Vibe-Coded GAS via `gas-fakes` and `ggsrun` Sandboxes

In local terminal workflows (VS Code / terminal) or cloud-hosted agent environments where users practice "Vibe Coding"—generating and running GAS scripts on the fly from natural language prompts—Layer 3: Fake-Sandbox Pre-Execution serves as a vital safety mechanism:

Dynamic Code Synthesis: An autonomous agent or developer prompts Gemini to generate a GAS script (e.g., "Clean up unorganized files across my project folder").
Sandboxed Dry-Run: Before executing against production Workspace infrastructure, the unverified script is executed inside a local or virtual Fake-Sandbox powered by gas-fakes or ggsrun.
Pre-Execution Threat Neutralization: Sandboxes intercept and block destructive operations (such as DriveApp.getFileById().setTrashed(true) or unauthorized GmailApp.sendEmail() broadcasts), infinite loops, and scope violations.
Verified Production Deployment: Only scripts that pass all sandbox safety assertions are pushed to production Google Workspace environments via MCP or clasp / ggsrun.

For a comprehensive architectural breakdown, refer to Orchestrating Google Workspace with Antigravity CLI: A High-Performance Agentic Framework.

Key Advantages

Zero Contamination of Production Databases: Strict 2-tier validation completely eliminates broken schemas, type errors, and hallucinated fields.
Safe Execution of Vibe-Coded Scripts: gas-fakes and ggsrun sandboxing engines ensure dynamically synthesized code cannot corrupt enterprise files or trigger unintended operations.
Early Detection and Automated Retry: Self-correcting retry loops feed validation errors back to Gemini prompts for automatic query adjustment.

Limitations and Operational Considerations

Schema Synchronization: When business rules evolve, both the responseSchema definition and GAS validation arrays must be updated in sync.

Advanced Patterns and Extensions

AI-Generated SQL Sanitization: Regex filters scan AI-generated SQL queries for destructive commands (DROP, DELETE) before execution.
Template Placeholder Verification: Ensures AI translations preserve required template tokens (e.g., {userName}, {orderId}).
Master Data Cross-Referencing: Validates that AI-extracted customer names or product IDs exist in master spreadsheets using fast Set/Map lookups.

9. Human-in-the-Loop (HITL) Interactive Approval Workflows

Figure 9: Human-in-the-Loop interactive approval workflow architecture — Illustrates AI drafting followed by mandatory spreadsheet checkbox authorization (onEdit) before irreversible email dispatch.

Concrete Example: AI Response Drafting and Spreadsheet-Based One-Click Approval

As illustrated in Figure 9, the Human-in-the-Loop (HITL) approval workflow executes through five secure stages:

Customer submits an inquiry email; Gemini analyzes the context and drafts a suggested response.
The draft is staged in the "ApprovalQueue" sheet or saved in Gmail's "Drafts" folder.
A support manager reviews the draft and clicks the "Approve" checkbox in column E.
An installable onEdit trigger immediately detects the approval event.
GAS executes the finalized email dispatch, records timestamped completion, and clears the checkbox.

Execution Instructions

Open the Apps Script editor attached to your Google Sheet.
Paste the script below into Code.gs.
Select setupTestApprovalQueue from the function dropdown and click [Run] to automatically scaffold the "ApprovalQueue" sheet with sample records and checkboxes.
Navigate to Triggers > [Add Trigger], select onEditTrigger, and set the event type to "On edit".
Return to the sheet and check the box in column E to trigger the live email dispatch.

Production Script (Interactive Checkbox Approval Gate)

/**
 * Test setup function: scaffolds the approval sheet and sample records
 */
function setupTestApprovalQueue() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  let sheet = ss.getSheetByName("ApprovalQueue");
  if (!sheet) {
    sheet = ss.insertSheet("ApprovalQueue");
  }
  sheet.clear();
  sheet.appendRow(["CustomerEmail", "DraftID", "Subject", "BodyDraft", "Approve", "Status", "Timestamp"]);

  sheet.appendRow([
    Session.getActiveUser().getEmail() || "test@example.com",
    "draft_001",
    "Customer Support Response",
    "Thank you for contacting enterprise support. Regarding your inquiry...",
    false,
    "PENDING_REVIEW",
    ""
  ]);
  sheet.getRange("E2").insertCheckboxes();
  SpreadsheetApp.flush();
  Logger.log("Approval queue scaffolded. Check box E2 to test live dispatch.");
}

/**
 * Installable onEdit trigger monitoring human approval checkboxes.
 * Dispatches customer communications only when explicitly approved.
 */
function onEditTrigger(e) {
  if (!e || !e.range) return;

  const sheet = e.range.getSheet();
  if (sheet.getName() !== "ApprovalQueue") return;

  const row = e.range.getRow();
  const col = e.range.getColumn();

  // Column 5: Approval Checkbox (TRUE / FALSE)
  // Column 6: Execution Status
  if (col === 5 && e.value === "TRUE") {
    const status = sheet.getRange(row, 6).getValue();
    if (status === "APPROVED_AND_SENT") return;

    const customerEmail = sheet.getRange(row, 1).getValue();
    const emailSubject = sheet.getRange(row, 3).getValue();
    const aiDraftBody = sheet.getRange(row, 4).getValue();

    if (!customerEmail || !aiDraftBody) {
      sheet.getRange(row, 6).setValue("ERROR: Missing Fields");
      return;
    }

    // 1. Dispatch finalized email
    GmailApp.sendEmail(customerEmail, emailSubject, aiDraftBody);

    // 2. Lock row status to prevent duplicate dispatches
    sheet.getRange(row, 6).setValue("APPROVED_AND_SENT");
    sheet.getRange(row, 5).clearContent(); // Clear checkbox
    sheet.getRange(row, 7).setValue(new Date());

    SpreadsheetApp.getActiveSpreadsheet().toast(
      `Email dispatched to ${customerEmail}`,
      "Approval Complete"
    );
  }
}

⚠️ Important Trigger Requirement

Simple onEdit(e) triggers run in restricted read-only authorization mode and cannot invoke GmailApp.sendEmail(). You must configure an Installable Trigger via Triggers > [Add Trigger] > [On edit].

Key Advantages

Zero Accidental Dispatches: AI drafts emails and classifies tickets, but irreversible actions require human approval.
Intuitive Collaborative Console: Operational managers approve tasks directly within familiar spreadsheet interfaces.

Limitations and Operational Considerations

Rapid Clicking Race Conditions: When users check multiple boxes rapidly, use LockService to prevent race conditions.

Advanced Patterns and Extensions

Executive Expense Authorization: Department heads check approval boxes on expense reports, triggering automated bank CSV export and accounting notifications.
Applicant Screening Gates: HR reviewers inspect AI-screened candidate profiles and check boxes to trigger automated interview invitation emails.

10. External SaaS Webhook Ingestion & Secure Proxy Gateways

Figure 10: Secure proxy gateway ingesting external SaaS webhooks and shielding API keys — Illustrates zero-trust webhook ingestion, server-side secret encapsulation via PropertiesService, and downstream API forwarding.

Concrete Example: External SaaS Webhook Ingestion & Secure Proxy Gateways

As illustrated in Figure 10, the secure proxy gateway operates across four zero-trust stages:

External SaaS platforms (GitHub, Stripe, Slack) transmit event webhooks to the GAS Web App endpoint.
GAS validates HMAC request signatures or Bearer tokens to eliminate unauthorized traffic.
GAS retrieves sensitive third-party API credentials from PropertiesService, keeping secrets completely hidden from AI prompts and client contexts.
Gemini analyzes the payload for task priority, and GAS posts structured tasks downstream while synchronizing Workspace records.

Execution Instructions

Open [Project Settings] > [Script Properties] and add property SAAS_API_SECRET_KEY with your SaaS API token.
Paste the script below and run testSecurePostTaskToExternalSaaS to verify that external payloads are dispatched with server-side injected credentials.

Production Script (Credential-Shielded Task Forwarding)

/**
 * Test function: execute from Apps Script editor
 */
function testSecurePostTaskToExternalSaaS() {
  securePostTaskToExternalSaaS(
    "Q3 Financial Report Synthesis",
    "AI-summarized task: Aggregate multi-currency ledgers and compile summary slide deck."
  );
}

/**
 * Forward AI-summarized tasks securely to an external SaaS project management tool.
 */
function securePostTaskToExternalSaaS(taskTitle, taskDetail) {
  // Retrieve SaaS secrets from encrypted Script Properties
  // Secrets are NEVER exposed to client browsers or LLM prompts
  const saasApiKey = PropertiesService.getScriptProperties().getProperty("SAAS_API_SECRET_KEY");
  const endpoint = "https://api.example-saas.com/v1/tasks";

  const payload = {
    title: taskTitle,
    description: taskDetail,
    createdAt: new Date().toISOString(),
  };

  const options = {
    method: "post",
    headers: {
      Authorization: `Bearer ${saasApiKey}`,
      "X-Custom-Header": "GAS-Secure-Proxy",
      "Content-Type": "application/json",
    },
    payload: JSON.stringify(payload),
    muteHttpExceptions: true,
  };

  const response = UrlFetchApp.fetch(endpoint, options);
  Logger.log(`External API Response Status: ${response.getResponseCode()}`);
}

Key Advantages

Prompt Injection Resilience: Even if an LLM is manipulated via adversarial inputs, it cannot leak corporate API keys because authentication headers are injected server-side by GAS.
Centralized SaaS Routing: Consolidates authentication flows (Bearer tokens, Basic auth, HMAC signatures) across multiple SaaS vendors.

Limitations and Operational Considerations

Payload Size Limits: Standard UrlFetchApp requests support payloads up to 50 MB.

Advanced Patterns and Extensions

Customer Support Router: Classifies incoming Zendesk/Intercom webhooks with Gemini and routes urgent tickets to Jira and VIP notices to Slack.
Payment Dispute Orchestrator: Ingests Stripe dispute webhooks, retrieves customer transaction logs from Drive, and prepares an audit dossier.

11. High-Throughput Hybrid Batch Processing & Prompt Request Packing

Figure 11: Hybrid batch processing architecture combining deterministic logic and packed AI inference — Illustrates zero-cost in-memory pre-screening for 98% of rows and chunked request packing for the remaining 2% edge cases.

Technical Overview and Official References

Processing tens of thousands of spreadsheet rows with LLMs incurs prohibitive latency and cost. As illustrated in Figure 11, applying Deterministic Screening (filtering 98% of standard rows using in-memory JavaScript regexes at $0 cost) and Prompt Request Packing (chunking 20 unstructured rows into a single batched JSON array payload) reduces API invocations by up to 95% while staying well within the GAS 6-minute execution window.

Batch Operations Best Practices: Google Sheets Best Practices
Time-driven Triggers Guide: Installable Triggers

Concrete Example: Cleansing 10,000 Customer Records with Request Packing

As illustrated in Figure 11 and Figure 11-1, high-throughput hybrid batch processing combines two optimization stages:

The script ingests thousands of raw spreadsheet rows into memory in a single read operation.
Deterministic Pre-Screening: In-memory JavaScript regexes cleanse 98% of standard rows in milliseconds at zero API cost.
Chunked Request Packing: The remaining 2% of unstructured edge cases are packed into chunks of 20 items per JSON array prompt, requiring only 10 API requests instead of 200.
Parsed results are written back to Google Sheets in a single batch, avoiding platform timeouts and slashing API costs by 98%.

Batch Packing Architecture Overview

Figure 11-1: High-Throughput Hybrid Batch Processing & Prompt Request Packing Architecture — Illustrates the multi-stage pipeline combining zero-cost in-memory pre-screening for 98% of rows and chunked request packing for the remaining 2% edge cases.

Execution Instructions

Open your Apps Script project and register GEMINI_API_KEY under Script Properties.
Paste the script below into Code.gs.
Run setupSampleDataAndRunBatch from the function dropdown to scaffold sample customer rows and execute the hybrid batch pipeline with request packing.

Production Script (Chunked Request Packing)

/**
 * Test setup function: scaffolds sample dataset and triggers batch execution
 */
function setupSampleDataAndRunBatch() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  let sheet = ss.getSheetByName("RawCustomerData");
  if (!sheet) {
    sheet = ss.insertSheet("RawCustomerData");
  }
  sheet.clear();
  sheet.appendRow(["PhoneNumber (Raw)"]);

  const sampleRows = [
    ["090-1234-5678"],
    ["03-1234-5678"],
    ["09012345678"],      // Irregular (Routed to AI packing queue)
    ["080 9876 5432"],    // Irregular (Routed to AI packing queue)
    ["0120-111-222"]
  ];
  sheet.getRange(2, 1, sampleRows.length, 1).setValues(sampleRows);
  SpreadsheetApp.flush();

  processHybridBatch();
}

function processHybridBatch() {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("RawCustomerData");
  const data = sheet.getDataRange().getValues();
  const results = [];
  const aiQueue = [];

  const phoneRegex = /^0\d{1,4}-\d{1,4}-\d{4}$/; // Standard format checker

  // Step 1: Fast deterministic screening in GAS memory ($0 cost)
  for (let i = 1; i < data.length; i++) {
    const rawPhone = String(data[i][0]).trim();
    if (phoneRegex.test(rawPhone)) {
      results.push([i + 1, data[i][0], "Deterministic_Cleansed", rawPhone]);
    } else {
      aiQueue.push({ rowIndex: i + 1, rawText: rawPhone });
    }
  }

  // Step 2: Pack edge cases into chunks of 20 items per API request
  if (aiQueue.length > 0) {
    const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
    const chunkSize = 20;

    for (let c = 0; c < aiQueue.length; c += chunkSize) {
      const chunk = aiQueue.slice(c, c + chunkSize);
      const prompt = `Normalize the following irregular phone number records into standard format (e.g., 090-1234-5678).
Return strictly a JSON array preserving the original item order.
Input List: ${JSON.stringify(chunk)}`;

      const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=${apiKey}`;
      const res = UrlFetchApp.fetch(url, {
        method: "post",
        contentType: "application/json",
        payload: JSON.stringify({
          contents: [{ parts: [{ text: prompt }] }],
          generationConfig: { responseMimeType: "application/json" },
        }),
        muteHttpExceptions: true,
      });

      if (res.getResponseCode() === 200) {
        const parsedResults = JSON.parse(
          JSON.parse(res.getContentText()).candidates[0].content.parts[0].text
        );
        parsedResults.forEach((item) => {
          results.push([
            item.rowIndex,
            item.rawText,
            "AI_Cleansed",
            item.normalized || item.rawText,
          ]);
        });
      }
    }
  }

  Logger.log(`Batch execution complete. Total records processed: ${results.length}`);
}

Key Advantages

95% Call Reduction via Packing: Compacting 200 edge cases into chunks of 20 reduces round-trip HTTP overhead from 200 requests to 10.
Zero-Cost Pre-Filtering: Deterministic JavaScript array operations filter thousands of items in memory in milliseconds.
6-Minute Platform Compliance: Dramatically minimized network round-trips guarantee execution finishes well within GAS limits.

Limitations and Operational Considerations

6-Minute Execution Limit: For datasets exceeding 50,000 items, implement continuation patterns using time-driven triggers.

Advanced Patterns and Extensions

Accounting Account Classification: Match 90% of known vendors via master dictionary lookups ($0) and pack the remaining 10% for AI inference.
Mass Product Review Sentiment Analysis: Star 5 and Star 1 reviews are scored by numerical logic; ambiguous Star 2–4 reviews are batch-analyzed with Gemini.

12. Token & Cost Optimization via CacheService and PropertiesService

Figure 12: Multi-tier caching architecture with CacheService and PropertiesService — Illustrates cryptographic MD5 prompt hashing, sub-millisecond in-memory cache retrieval, and API bypass optimization.

Technical Overview and Official References

Google Apps Script provides two primary native storage services for state and data persistence across executions: CacheService, an ultra-fast in-memory transient key-value cache (retaining entries for up to 6 hours / 21,600 seconds), and PropertiesService, an encrypted persistent key-value store. Combining these services constructs a high-performance multi-tier caching layer that eliminates duplicate LLM inferences and achieves sub-millisecond response latencies.

Cache Service Reference: Official Guide
Properties Service Reference: Official Guide

Concrete Example: Semantic Response Caching via Prompt Hashing

As illustrated in Figure 12, multi-tier caching minimizes latency and duplicate costs through four sequential checks:

The script computes a unique cryptographic MD5 hash key from the input prompt string.
GAS queries CacheService (in-memory cache); on a cache hit, the response returns instantly in sub-milliseconds with zero API cost.
On a cache miss, GAS dispatches the request to the Gemini API endpoint.
The generated response is stored in CacheService (up to 6 hours) and PropertiesService for future requests.

Execution Instructions

Open [Project Settings] > [Script Properties] and configure GEMINI_API_KEY.
Paste the script below into Code.gs.
Run testCallGeminiWithCache from the function dropdown twice consecutively.
Observe in the execution log that Run 1 invokes the live Gemini API, while Run 2 hits the sub-millisecond in-memory cache instantly.

Production Script (MD5 Hashed Prompt Caching)

/**
 * Test function: execute twice to observe cache hit behavior
 */
function testCallGeminiWithCache() {
  const prompt = "What is the single greatest advantage of Google Apps Script?";

  const start1 = new Date().getTime();
  const res1 = callGeminiWithCache(prompt);
  const elapsed1 = new Date().getTime() - start1;
  Logger.log(`[Run 1 (API Invocation)] Latency: ${elapsed1}ms | Response: ${res1.trim()}`);

  const start2 = new Date().getTime();
  const res2 = callGeminiWithCache(prompt);
  const elapsed2 = new Date().getTime() - start2;
  Logger.log(`[Run 2 (Cache Hit)] Latency: ${elapsed2}ms | Response: ${res2.trim()}`);
}

/**
 * Executes Gemini API requests with automatic multi-tier caching.
 */
function callGeminiWithCache(promptText) {
  // 1. Generate unique MD5 hash key for prompt
  const rawHash = Utilities.computeDigest(
    Utilities.DigestAlgorithm.MD5,
    promptText,
    Utilities.Charset.UTF_8
  );
  const hashKey = rawHash.map((b) => (b < 0 ? b + 256 : b).toString(16).padStart(2, "0")).join("");
  const cacheKey = `ai_cache_${hashKey}`;

  const cache = CacheService.getScriptCache();
  const ttlSeconds = 21600; // 6 hours

  // 2. Return cached response if available
  const cachedResponse = cache.get(cacheKey);
  if (cachedResponse) {
    Logger.log(`Cache Hit: ${cacheKey}`);
    return cachedResponse;
  }

  // 3. Dispatch to Gemini API on cache miss
  const apiKey = PropertiesService.getScriptProperties().getProperty("GEMINI_API_KEY");
  const url = `https://generativelanguage.googleapis.com/v1beta/models/gemini-3.6-flash:generateContent?key=${apiKey}`;

  const response = UrlFetchApp.fetch(url, {
    method: "post",
    contentType: "application/json",
    payload: JSON.stringify({ contents: [{ parts: [{ text: promptText }] }] }),
    muteHttpExceptions: true,
  });

  const json = JSON.parse(response.getContentText());
  const generatedText = json.candidates[0].content.parts[0].text;

  // 4. Cache response for 6 hours (21,600 seconds)
  cache.put(cacheKey, generatedText, ttlSeconds);
  return generatedText;
}

Key Advantages

Zero Duplicate Inference Cost: Repetitive queries and re-evaluated formulas return instant cached results at $0 cost.
Ultra-Low Latency: Network round-trips (1–3 seconds) drop to in-memory lookup times (sub-milliseconds).
Rate Limit Resilience: Shields downstream APIs from 429 Too Many Requests errors during sudden traffic spikes.

Limitations and Operational Considerations

Cache Capacity Boundaries: CacheService limits individual cache entries to 100 KB. For large text corpora, store intermediate blobs in Drive or PropertiesService.

Advanced Patterns and Extensions

OAuth Access Token Caching: Cache SaaS bearer tokens matching their expiration window (e.g., 3,600s), avoiding redundant token exchanges.
Multi-Turn Session Context: Maintain recent conversation state in CacheService across Web App interactions for fluid multi-turn dialogues.

Conclusion: Architectural Blueprint for Google Workspace Automation in the AI Era

The exponential advancement of Generative AI has fundamentally reshaped the Google Workspace automation landscape. Far from signaling the demise of Google Apps Script, it establishes a crystal-clear Separation of Concerns: Generative AI serves as the probabilistic reasoning brain, while Google Apps Script acts as the deterministic execution hands, feet, and nervous system.

By combining generative reasoning with deterministic execution, enterprise teams achieve software quality and governance unreachable by either tool in isolation.

1. Separation of Concerns Matrix: Generative AI vs. Google Apps Script

Architecture Dimension	Generative AI (Gemini / Workspace Studio / Spark)	Google Apps Script (GAS)
Optimal Data Types	Ambiguous natural language, unstructured text, media	Structured schemas, JSON, tabular numbers, master records
Execution Paradigm	Probabilistic & Flexible Reasoning (Context, summaries)	Deterministic & 100% Reproducible Execution (Math, validation)
Trigger Mechanisms	Prompt interaction, autonomous schedules, agent goals	Form submissions, cell edits (`onEdit`), cron timers, Webhooks
Security & Auth	Semantic interpretation (Unsuitable for holding raw secrets)	Encrypted storage (`PropertiesService`), secure proxy dispatch
Cost & Latency	Per-token pricing, inference latency (seconds)	Zero-cost serverless execution, in-memory caching (milliseconds)
UI Integration	Chat panels, prompt dialogs	Formula custom functions (spill), sidebars, modal dialogs, menus

2. Four Practical Principles for Enterprise-Grade Automation

Principle 1: Separate the Brain from the Nervous System and Fix Scripts for Determinism Delegate fuzzy semantic understanding, creative synthesis, and unstructured extraction to AI models. Delegate mathematical calculations, rigid business rules, state persistence, and OAuth management to GAS. For routine workflows, compile natural-language instructions into fixed GAS scripts rather than repeatedly invoking runtime LLM API reasoning, thereby guaranteeing 100% deterministic reproducibility and sub-second execution latency. Never spend tokens where a deterministic JavaScript regex or array filter can execute for free in milliseconds.
Principle 2: Enforce Multi-Layered Guardrails and Sandboxing Never pipe raw LLM text directly into mission-critical systems. Enforce strict JSON Schemas (responseSchema) at the model layer and validate types, boundaries, and foreign keys in GAS before committing writes. For dynamically generated script code, perform pre-execution dry-runs in sandboxed environments (gas-fakes).
Principle 3: Gate High-Stakes Actions with Human Authorization (HITL) For operations involving external data transmission, destructive modifications, or monetary transactions, design systems that produce drafts or staging rows, requiring explicit human sign-off (via checkboxes or dialogs) before irreversible execution.
Principle 4: Optimize Throughput via Hybrid Batching and Request Packing Maximize throughput and respect platform execution windows (e.g., the GAS 6-minute ceiling) by screening standard cases with deterministic code and packing residual unstructured items into batch prompts. Couple this with multi-tier in-memory caching to minimize operational costs.

3. To the Engineers Pioneering the Next Generation of Workspace Automation

Google Apps Script has matured into a fully recognized Google Workspace Core Service Ref. With Gemini embedded directly in the script editor Ref and professional CLI tooling (@google/clasp, ggsrun, gas-fakes) Ref, the developer experience has reached unprecedented heights.

In an era where AI writes code, the supreme value of the software engineer lies not in rote syntax memorization, but in holistic system architecture design and the elegant orchestration of probabilistic intelligence with deterministic cloud substrates.

By harmonizing the cognitive agility of Generative AI with the rock-solid execution foundation of Google Apps Script, developers can architect the resilient, intelligent, and scalable enterprise automations of tomorrow.

Preventing Quota Crashes via Antigravity CLI Agent Hooks

Tanaike — Wed, 12 Aug 2026 07:15:38 +0000

Solving the LLM quota monitoring paradox with zero-overhead local Connect RPC agent hooks.

Abstract

Google Antigravity CLI users using Google OAuth face abrupt task failures when API quota hits 0%, while account switching triggers unrecoverable signature errors. Querying quota via LLM tool calls creates a paradox by consuming the very tokens being monitored. We resolve this with antigravity-cli-check-usage-plugin, a CLI Agent Hook running outside the LLM execution turn. Directly querying local Connect RPC endpoints, it monitors quota with zero token overhead and injects proactive warning banners when threshold limits are reached.

1. Introduction

Developers relying on Google Antigravity CLI for autonomous pair programming frequently encounter a frustrating barrier: running out of API quota mid-session. When using Google OAuth authentication, your quota can silently hit 0%, causing task execution to halt abruptly with an unrecoverable quota error:

⚠ Individual quota reached. Please upgrade your subscription to increase your limits. Resets in 1h00m00s.
Error ID: 49a81c0f

To bypass this roadblock, developers often attempt to log out and switch to a paid Google Cloud project billing account. However, in Antigravity CLI v1.1.12, attempting to resume an active agent session after switching accounts triggers a critical signature mismatch failure:

⚠ Invalid thought signature.
Error ID: e2901f4c

This error prevents the session from continuing, forcing you to wait until the quota resets. While future CLI updates may resolve this session state issue, waiting for a patch is not a viable strategy when shipping code today.

The architectural divergence between standard tool-based monitoring and our agent hook model is illustrated in Figure 1. While developers can manually run the /usage slash command to view quota, AI agents executing multi-step autonomous tasks cannot trigger /usage programmatically. In traditional CLI workflows, invoking quota checks via LLM tool calls requires passing context back and forth through the inference API, depleting active model tokens. Conversely, the zero-overhead agent hook interceptor executes locally prior to prompt dispatch, querying the process socket silently and injecting status alerts only when remaining quota breaches configured safety bounds.

In this article, to overcome the limitation of agents being unable to trigger /usage, we walk through the engineering journey of building antigravity-cli-check-usage-plugin. By combining local Connect RPC inspection with proactive lifecycle hooks, this plugin automatically performs external quota checks with Zero Quota Consumption (0 LLM tokens), completely preventing mid-session crashes.

2. Repository

The plugin developed and discussed in this article is open-sourced and available on GitHub:

GitHub Repository: tanaikech/antigravity-cli-check-usage-plugin

This repository contains the dual-runner entrypoint (entrypoint.sh), Python script (check_quota.py), pure Bash fallback script (check_quota.sh), lifecycle hook manifest (hooks.json), and default threshold configuration (config.json), allowing instant one-command installation as an Antigravity CLI plugin across any developer environment.

3. Core Motivation

While Antigravity CLI provides the /usage slash command for developers to manually inspect quota limits, AI agents executing autonomous task loops cannot invoke /usage programmatically.

If we attempted to solve this by equipping the AI agent with a custom tool to query the internal RPC endpoint (/exa.language_server_pb.LanguageServerService/GetUserStatus), the tool invocation and context turns would consume LLM API tokens. This creates a fundamental paradox: using LLM context tokens to check remaining quota consumes the very quota you are trying to preserve.

In addressing this challenge, the solution built upon our previously published article, A Developer’s Guide to Agent Hooks in Antigravity CLI. Recalling the out-of-band execution mechanics of CLI Agent Hooks explored in that guide, we leveraged lifecycle events (PreInvocation and PostInvocation) to run local process checks completely outside the LLM inference turn—guaranteeing zero API token quota overhead.

Zero Token Overhead: During normal operation, quota checking runs entirely outside the LLM context (via local Python/Bash scripts) without invoking LLM tool calls.
Local RPC Interception: It automatically queries the CLI's internal status endpoint on 127.0.0.1 without external network calls.
Proactive Threshold Alerting: It notifies both the developer and the AI agent before quota hits 0%, preventing session corruption and hard crashes.

4. Connect RPC

Through reverse-engineering the Antigravity CLI local process architecture (originally explored in the antigravity-usage repository by skainguyen1412), we discovered that the running agy process hosts a local HTTPS server using the gRPC / Connect Protocol on 127.0.0.1.

By querying the internal endpoint /exa.language_server_pb.LanguageServerService/GetUserStatus, we can retrieve real-time model quota fractions and reset timestamps directly from the local process.

Because the agy process may open multiple listening sockets on 127.0.0.1 for IPC and WebSockets, a shell loop that probes each detected port until it receives a valid userStatus response is required:

# Scan listening sockets for the active 'agy' process on loopback (127.0.0.1)
for PORT in $(ss -tulpn 2>/dev/null | grep agy | awk -F'127.0.0.1:' '{print $2}' | awk '{print $1}' | sort -u); do
  # Post a Connect Protocol request to the internal GetUserStatus RPC endpoint
  RES=$(curl -k -s -X POST https://127.0.0.1:${PORT}/exa.language_server_pb.LanguageServerService/GetUserStatus \
    -H "Content-Type: application/json" \
    -H "Connect-Protocol-Version: 1" \
    -d '{"metadata":{"ideName":"antigravity","extensionName":"antigravity","locale":"en"}}')

  # Verify if the response contains the userStatus JSON key
  if echo "$RES" | grep -q "userStatus"; then
    echo "$RES" | jq .
    break
  fi
done

To execute this logic seamlessly and rapidly inside an agent hook outside the LLM invocation turn, we implemented a Python script using standard library components, alongside a pure Bash fallback script (check_quota.sh) and an entrypoint runner (entrypoint.sh) that automatically selects Python when available or Bash on systems without Python installed.

[!IMPORTANT]

Note on Scope: The GetUserStatus endpoint returns the Five Hour Limit Remaining fraction (remainingFraction) and ISO reset timestamp (resetTime) for active model pools. The long-term Weekly Limit Remaining is not exposed through this RPC endpoint.

5. Complete Agent Hook Workflow

Building upon the lifecycle concepts detailed in A Developer’s Guide to Agent Hooks in Antigravity CLI, the plugin integrates into the Antigravity CLI by registering PreInvocation and PostInvocation agent hooks in hooks.json. Because PreInvocation fires after the user submits input but before the prompt payload is dispatched to the LLM backend, it inspects local process state and dynamically injects steps prior to model inference.

As detailed in Figure 2, the final agent hook operates under two distinct execution patterns based on the configured warning threshold (default: 20%):

Pattern A: Normal Operation (Quota > Threshold)

When remaining quota is above the warning threshold, the hook outputs an empty step injection payload:

{
  "injectSteps": []
}

Impact: Zero Quota Consumption (0 Token Overhead). The hook executes silently in less than 50 milliseconds. No messages or extra context are injected into the LLM session, consuming absolutely zero model quota.

Pattern B: Warning State (Quota <= Threshold)

When remaining quota drops to or below the threshold, the hook injects a transient system message with mandatory agent directives:

{
  "injectSteps": [
    {
      "ephemeralMessage": "⚠️ [SYSTEM QUOTA WARNING] Model quota is below threshold (20%) (Active: gemini-3.6-flash-medium):\n - GEMINI Models [ACTIVE MODEL]: 20.0% remaining (Refreshes in 3h 00m)\n\n[MANDATORY INSTRUCTION FOR AGENT]: The model quota has dropped below the threshold. You MUST display a prominent Quota Warning banner at the very top of your response for THIS TURN ONLY! Do NOT display a warning banner on subsequent turns unless another quota warning is explicitly injected. In the warning banner, you MUST also inform the user that they can run the '/usage' command at any time to inspect detailed quota status."
    }
  ]
}

Impact: The AI agent immediately prepends a prominent Quota Warning banner to its response, advising the developer to run /usage or pause heavy multi-step automation before encountering a hard crash.

6. Installation & Dual Runtime

The complete implementation is published as an open-source Antigravity CLI plugin: antigravity-cli-check-usage-plugin.

Installation

Install the plugin directly via the Antigravity CLI:

agy plugin install https://github.com/tanaikech/antigravity-cli-check-usage-plugin

Dual Runtime Architecture: Python Primary + Pure Bash Fallback

The plugin features a multi-environment entrypoint (entrypoint.sh) producing 100% identical JSON outputs across both runtimes. The engineering rationale behind this dual design includes:

Python (Primary Runner): Requires zero external dependencies like jq, absorbs OS-specific syntax differences across Linux, macOS, and Windows, and guarantees type-safe date math.
Pure Bash (Fallback Safety Net): Ensures instant execution in minimal or containerized environments where Python is not pre-installed.

Configuration and Disabling

You can customize or completely disable the warning threshold (default: 20.0%) using environment variables, configuration files, or hook arguments.

Set Custom Threshold (e.g., 25%):

export QUOTA_THRESHOLD=25.0

Disable Quota Check Completely:
Setting QUOTA_THRESHOLD to -1 instructs the hook to skip all RPC queries immediately:

export QUOTA_THRESHOLD=-1

7. Real-World Testing & Verification

After installing the plugin, setting export QUOTA_THRESHOLD=80.0 and executing a live session test in Antigravity CLI v1.1.12 demonstrates the hook in action, as captured in Figure 3:

When the user enters a simple greeting (hello), the agent hook instantly detects that the active model's remaining quota (71.0%) has dropped below the configured threshold (80.0%). A prominent yellow Warning banner (Quota Warning: GEMINI Models quota is at 71.0% remaining...) is dynamically prepended at the top of the AI's response, alerting the developer and providing a reminder to inspect detailed limits via /usage.

8. Updating & Uninstalling

To update the plugin to the latest version or remove it from your environment:

Check installed plugins:

  agy plugin list

Uninstall the plugin:

  agy plugin uninstall antigravity-cli-check-usage-plugin

Reinstall the updated version:

  agy plugin install https://github.com/tanaikech/antigravity-cli-check-usage-plugin

Summary

In this article, we presented a zero-overhead solution to eliminate mid-session quota crashes and account-switching signature errors in Google Antigravity CLI. Drawing upon foundational concepts from A Developer’s Guide to Agent Hooks in Antigravity CLI and resolving the paradox where using LLM tool calls to query internal RPC endpoints consumes quota, we built native CLI Agent Hooks (PreInvocation / PostInvocation) running completely outside the LLM execution turn. Featuring a dual Python primary and pure Bash fallback architecture, the hook probes internal local Connect RPC endpoints with absolute zero token consumption during normal operation. By proactively injecting warning banners and /usage reminders when quota drops below threshold, it guarantees universal environment compatibility and eliminates task interruptions cleanly at the root.

Before the Quake: How Antigravity CLI's AI Agents & IoT Data Predict Earthquakes

Tanaike — Fri, 07 Aug 2026 02:55:21 +0000

Published Paper: Unification Theory of Lithosphere-Atmosphere-Ionosphere Coupling via Acoustic-Gravity Waves (LAIC-AGW) and Quantitative Pre- and Post-Seismic Anomaly Verification Using Ultra-Dense IoT Weather Sensor Networks (ESS Open Archive)

Abstract

We announce the publication of our updated manuscript on ESS Open Archive, establishing the Unified LAIC-AGW Theory using ultra-dense IoT weather data. Executed on Antigravity CLI with Gemini 3.6 Flash using the autonomous R&D framework tanaike-lab, this project integrates 71,107 authentic Netatmo observation records with seismic moment tensors ($M_{ij}$). By capturing pre-seismic thermodynamic enthalpy anomalies ($\delta \theta_e = 5.96\text{--}15.47\,\text{K}$) and acoustic-gravity waves through a deterministic signal processing pipeline, Haversine focal attenuation, and a Sigmoidal Bayesian probability model ($P_{\text{eq}} = 0.0\%\text{--}99.8\%$), this framework delivers 2 to 6 hours of advance lead time with 100% false alert elimination in non-epicentral regions. This milestone demonstrates how human researchers and autonomous AI multi-agent matrices co-create rigorous, empirical scientific breakthroughs.

1. Introduction

Today, on August 13, 2026, our updated geophysics research paper titled Unification Theory of Lithosphere-Atmosphere-Ionosphere Coupling via Acoustic-Gravity Waves (LAIC-AGW) and Quantitative Pre- and Post-Seismic Anomaly Verification Using Ultra-Dense IoT Weather Sensor Networks has been officially updated and released on the international open-access preprint server ESS Open Archive.

Conventional earthquake early warning systems (such as P-wave alerts) operate reactively by detecting seismic waves after fault rupture has already occurred, offering at most a few seconds to tens of seconds of warning time. In contrast, this study leverages continuous 20-minute weather big data collected across thousands of crowdsourced IoT weather stations (Netatmo) nationwide in Japan via the Netatmo API (totaling 71,107 authentic observation records). By coupling these atmospheric observations directly with seismic moment tensors ($M_{ij}$) via partial differential equations, we quantitatively demonstrate a "Proactive Earthquake Early Warning System" providing 2 to 6 hours of advance lead time.

The execution of this complex project—including partial differential equation solver integration, big data signal extraction, Popperian falsifiability verification, and manuscript preparation—was driven by the AI Co-Researcher framework tanaike-lab operating on Antigravity CLI powered by Gemini 3.6 Flash (for background on tanaike-lab, see our technical articles on Medium and DEV.to).

【Academic Note】: It should be emphasized that the physical models, data interpretations, inferences, and precursor warning conclusions presented in this paper represent one of many academic perspectives and methodologies regarding earthquake precursors and lithosphere-atmosphere coupling within the broad geophysics community. Given the inherent complexity of fault dynamics, these findings contribute a novel framework to the ongoing scientific discourse, inviting further empirical validation and community dialogue.

In this article, written specifically for AI practitioners, software architects, and technology leaders, we explore how human-AI collaboration on Antigravity CLI turned ultra-dense IoT sensor data into a proactive planetary defense platform.

2. Proactive vs. Reactive Warning: Turning Cities into Sensitive Skin

Figure 1: Executive infographic of the LAIC-AGW Unified Theory illustrating lithospheric seismic displacement, pre- and post-seismic acoustic-gravity wave (AGW) atmospheric excitation, Bolton (1980) exact equivalent potential temperature ($\theta_{e, \text{Bolton}}$) calculations, Haversine spherical distance mechanics, regional baseline extraction, and station-level focal attenuation decay.

Imagine living in a city where early warning alerts don't chime after the ground starts violently shaking, but hours before.

Existing early warning infrastructure relies on P-wave detectors placed near fault lines. When an earthquake strikes, P-waves travel at roughly $6\,\text{km/s}$, granting cities tens of kilometers away a brief 5 to 30 second window before destructive S-waves arrive. However, near the epicenter—where damage is most severe—people reside inside an inevitable "blind zone" where shaking hits before any alert can arrive.

Our Unified LAIC-AGW Theory shifts the paradigm from reactive seconds to proactive hours. Instead of waiting for subterranean rocks to snap, our system treats thousands of ultra-dense crowdsourced IoT weather stations (Netatmo) placed across metropolitan areas like a sensitive array of skin sensors. Hours prior to fault rupture, subtle physical anomalies—micro-barometric strain and thermal energy releases—are injected into the atmospheric boundary layer. Capturing these pre-seismic signatures unlocks a 2 to 6 hour advance lead time window, allowing smart cities to automatically decelerate high-speed trains, halt semiconductor lithography tools, isolate chemical pipelines, and safely evacuate citizens.

3. Accessible Atmospheric Physics: "Cold Sweat" and "The Drum Skin Analogy"

How does a solid Earth fault rupture manifest in surface weather sensors hours before shaking? The underlying physics can be understood through intuitive real-world analogies:

1. Pre-Seismic "Geophysical Cold Sweat" and Micro-Barometric "Creaking"

Hours before a major earthquake, tectonic stress accumulation along a fault plane creates microscopic fractures within crustal rock. This micro-fracturing releases radioactive radon gas, which ionizes air molecules in the boundary layer. These ionized air molecules act as condensation nuclei, causing ambient water vapor to condense and release latent heat energy into the atmosphere.

To detect this subtle thermal release, our system continuously calculates Equivalent Potential Temperature ($\theta_e$)—representing total atmospheric enthalpy (sensible plus latent heat)—from basic weather parameters: Barometric Pressure ($P$), Air Temperature ($T$), and Relative Humidity ($RH$). Hours prior to rupture, a prominent pre-seismic thermal spike ($\delta \theta_e = 5.96\text{--}15.47\,\text{K}$) emerges directly above the impending epicenter, acting like a "geophysical cold sweat" on the Earth's surface.

Simultaneously, localized crustal compression drives short-period residual pressure perturbations in the boundary layer, creating atmospheric "creaking sounds" prior to major shaking.

2. Atmospheric Wave Responses: "The Drum Skin Analogy"

The atmospheric excitation signature varies dramatically based on fault dislocation geometry, which can be visualized using a simple "drum skin" analogy:

Normal Faulting (Pulling the drum skin downward): Seafloor subsidence ($M_{zz} < 0$) excites sustained, long-period acoustic-gravity waves ($\Delta P_{\text{post}} = 255.60\,\text{hPa}$) that propagate outward in harmony with ocean tsunamis (2016 Fukushima M7.4).
Strike-Slip Faulting (Rubbing the drum surface horizontally): Although vertical displacement is minimal, intense shear friction generates powerful pre-seismic latent heat spikes ($\delta \theta_e = 14.36\,\text{K}$) directly above the epicenter, followed by directional post-rupture wave propagation (2018 Osaka M6.1, 2026 Kumamoto M7.1).
Reverse Faulting (Unclamping the drum skin): Rapid atmospheric pressure drops ($102.10\,\text{hPa/h}$) caused by passing typhoons reduce fault normal stress, unclamping fault friction and dynamically triggering rupture via positive Coulomb stress shifts (2018 Hokkaido M6.7 during Typhoon Jebi).

4. Data Processing Pipeline & False Alarm Suppression

Figure 2: Unified LAIC-AGW Mathematical and Physical Derivation Pipeline illustrating the 7-step progression from raw weather measurements ($P, T, RH$) to exact thermodynamic equivalent potential temperature $\theta_{e, \text{Bolton}}$, regional baseline residual extraction, Haversine focal weighting $W_{\text{focal}}$, API station density factor $\Phi_{\text{density}}$, Sigmoidal Bayesian probability derivation $P_{\text{eq}}^{\text{real}}$, post-seismic 3D AGW wave excitation, and thermal relaxation decay.

To transform raw, noisy crowdsourced IoT weather data into high-confidence alerts without triggering false alarms, our pipeline executes a 7-step signal processing flow:

Thermodynamic Conversion: Continuous streaming weather parameters $(P, T, RH)$ are converted via Bolton's (1980) exact formula into Equivalent Potential Temperature $\theta_{e, \text{Bolton}}$.
Regional Baseline Subtraction: Spatially averaging regional temperature trends ($\bar{\theta}_{e, \text{regional}}$) filters out synoptic meteorological fronts (e.g., passing cold fronts or typhoons).
Haversine Focal Decay: Spherical Haversine distance ($d_i$) to candidate epicenters is calculated, applying exponential attenuation $W_{\text{focal}, i} = \exp(-d_i / 250\,\text{km})$ to isolate localized anomalies.
API Station Density Completeness Factor: A density scaling factor $\Phi_{\text{density}}(N) = 1 - \exp(-N / 30)$ automatically scales down probabilities in sparse station zones to prevent over-confidence.
Sigmoidal Bayesian Forecasting Model: Log-odds metrics $L(\mathbf{X})$ compute exact prediction probabilities $P_{\text{eq}}^{\text{real}}(\%)$ ($0.0\%\text{--}99.8\%$).

Figure 3: Executive Infographic explaining the Spatial Relationship Between Epicenter Location and Sensor Array Area. Panel A shows Intra-Area Containment where the epicenter is located inside the sensor array, yielding high prediction probability $P_{\text{eq}} > 90\%$. Panel B shows Off-Epicentral Distance Scaling where the epicenter is situated outside the sensor array, causing exponential signal attenuation and scaling $P_{\text{eq}} < 5\%$.

Why Distant Cities Don't Suffer False Panic Alerts

A critical challenge in disaster prediction is eliminating false positives. As illustrated in Figure 3:

Panel A (Intra-Area Containment): When an epicenter lies directly inside the monitored sensor array ($d_{\text{min}} \to 0$), prediction probability peaks at maximum confidence ($P_{\text{eq}} = 89.4\%\text{--}99.8\%$, reaching $92.7\%\text{--}99.8\%$ in dense urban arrays).
Panel B (Off-Epicentral Scaling): When the epicenter lies outside the sensor array ($d_{\text{min}} > 150\,\text{km}$), exponential distance attenuation $\exp(-d_{\text{min}} / 250\,\text{km})$ smoothly scales prediction probabilities down to background levels ($P_{\text{eq}} \le 4.8\%$), mathematically guaranteeing 100% false alarm elimination in non-epicentral cities.

5. Empirical Results Across 71,107 Authentic Netatmo Records

Our study validated the LAIC-AGW Theory using 71,107 authentic observation records across four major Japanese earthquakes and one severe weather control event:

Earthquake Event	Evaluated Area	Pre-Seismic Enthalpy $\delta \theta_e$	Prediction Probability $P_{\text{eq}}$ (%)	Alert Level	Post-Seismic AGW Wave $\Delta P_{\text{post}}$	Spatial Isolation Performance
① 2016 Fukushima M7.4	Tokyo / Kanto [Target]	15.47 K	99.8%	CRITICAL	255.60 hPa	Epicenter Hit ($P = 99.8\%$)
	Osaka / Kansai	4.19 K	4.2%	LOW	12.40 hPa	False Positive Eliminated ($P = 4.2\%$)
② 2018 Osaka M6.1	Osaka / Kansai [Target]	6.79 K	92.7%	HIGH	37.10 hPa	Epicenter Hit ($P = 92.7\%$)
	Tokyo / Kanto	1.77 K	2.4%	LOW	4.20 hPa	False Positive Eliminated ($P = 2.4\%$)
③ 2018 Hokkaido M6.7	Hokkaido Area [Target]	5.96 K	89.4%	HIGH	256.10 hPa	Sparse Network Scaled ($P = 89.4\%$)
	Tokyo / Kanto	0.35 K	0.5%	LOW	8.40 hPa	False Positive Eliminated ($P = 0.5\%$)
④ 2026 Kumamoto M7.1	Fukuoka / Kyushu [Target]	14.36 K	99.6%	CRITICAL	257.20 hPa	Epicenter Hit ($P = 99.6\%$)
	Tokyo / Kanto	1.73 K	2.3%	LOW	9.10 hPa	False Positive Eliminated ($P = 2.3\%$)
⑤ 2018 Typhoon 18 (Control)	All Regions (Kanto / Kansai / Kyushu)	0.85 K	1.2%	LOW	18.40 hPa	0.0% False Positive Rate ($P = 1.2\%$)

Figure 4: Empirical Performance Comparison Chart Across 4 Major Earthquakes and 1 Control Event. Displays side-by-side comparative bar charts comparing Old Model v3.2 and Updated Model v7.0 across Sensitivity (%), False Positive Count (100% elimination), Overall Accuracy (%), and Signal-to-Noise Ratio (SNR).

As shown in Figure 4, our updated model achieved major empirical breakthroughs across 71,107 records:

Sensitivity: Boosted from $64\%\text{--}73\%$ to $77\%\text{--}89\%$.
Overall Accuracy: Improved from $74\%\text{--}86\%$ to $94\%\text{--}99\%$.
Signal-to-Noise Ratio (SNR): Jumped from $<8\,\text{dB}$ to **$>21\,\text{dB}$** (an 8-fold signal boost).
False Positives: Reduced from 8–18 false alerts down to 0 false positives (100% false alarm elimination) across all non-target cities and control weather scenarios.

6. Actionable Infrastructure Mitigation

Figure 5: Application 1: Smart City and Critical Infrastructure Early Mitigation Network illustrating automated bullet train pre-deceleration, semiconductor EUV lithography stepper suspension, toxic gas valve shutoff, and smart elevator emergency parking triggered 2 to 6 hours before rupture.

A 2 to 6 hour pre-seismic lead-time window transforms municipal disaster management:

Shinkansen Bullet Trains: High-speed trains automatically reduce speeds from $300\,\text{km/h}$ to crawling speeds prior to shaking, preventing catastrophic derailments.
Semiconductor EUV Fabrication: EUV lithography steppers park in safe rest modes, protecting multi-billion-dollar optical mirror alignments.
Toxic Industrial Gas Lines: Automated shut-off valves close chemical pipelines, preventing toxic leaks and urban fires.
Smart Elevators: High-rise elevators descend to the nearest floor and park open-doored, eliminating passenger entrapment.

7. Inside the AI Co-Researcher Framework (`tanaike-lab`) on Antigravity CLI

Executing complex partial differential equations, ingesting 71,107 IoT records, and running multi-axis peer reviews was accomplished using Antigravity CLI powered by Gemini 3.6 Flash and the auxiliary R&D framework tanaike-lab.

Figure 6: Autonomous R&D workflow of tanaike-lab running on Antigravity CLI powered by Gemini 3.6 Flash.

1. The Human-AI Collaborative Co-Creation Lifecycle & Specialized Subagents Matrix

As shown in Figure 6, tanaike-lab operates through a tightly coupled human-AI loop driven by a matrix of specialized subagents:

Human Strategic Vision: The human Principal Investigator (PI) sets the research hypothesis: coupling Netatmo IoT weather archives with seismic moment tensors ($M_{ij}$) to build a unified LAIC-AGW theory.
AI Plan Audit & Mathematical Physics Derivation: Specialized subagents (plan_audit_dryrun_agent and theoretical_refinement_physicist) inspect the plan, adding cubic spline interpolation, Morlet wavelets, spatial array beamforming (+18 dB SNR boost), Dobrovolsky strain radii ($R_{\text{prep}} = 10^{0.43M}$), Haversine focal attenuation ($W_{\text{focal}}$), and station density completeness ($\Phi_{\text{density}}$).
Automated Code Development & Popperian Self-Healing: The code execution agent (experiment_code_developer) writes Python data processing scripts inside an isolated sandbox, injecting automated assertion hooks (assert) to repair debug loops autonomously upon encountering runtime errors.
Big Data Analysis & Agent-to-Agent (A2A) Peer Reviews: Specialized subagents (experimental_results_auditor, blind_calibration_auditor, theory_discussion_reviewer) run A2A peer discussions to verify pre-seismic enthalpy spikes ($\delta \theta_e = 15.47\,\text{K}$), execute zero-hindsight blind evaluations, and confirm Typhoon 18 control noise suppression (0.0% false alert rate).
Manuscript Peer Review & Article Refinement: A 5-axis simulated peer review panel and article_editorial_architect audit citation integrity (100% 1-to-1 matching), LaTeX compilation, and developer-focused article readability before final PI review.

2. Real-Time Self-Crystallization & CLI Auto-Reinstallation Engine

Unlike static agent scripts, tanaike-lab features an active Real-Time Self-Crystallization & CLI Auto-Reinstallation Engine:

Real-Time Directive Capture: Human steering directives and verified execution lessons are captured on the fly during project runs.
SKILL.md Auto-Crystallization: Lessons are written immediately into SKILL.md.
CLI Plugin Auto-Reinstallation: An automated export engine (scripts/auto_crystallize_and_export.py) exports and reinstalls the updated skill matrix directly into the local Antigravity CLI plugin directory on the fly, performing instant Git remote sync to keep the framework continuously evolving.

3. Academic and Systemic Positioning & Triple-Domain Architecture

Within modern technology R&D, tanaike-lab is positioned as a "Human-Centric Dynamic Virtual R&D Laboratory OS":

Positioning Against "AI Slop" vs. Human-AI Synergy: Unsupervised AI generation frequently suffers from hallucinations and lack of domain rigor ("AI slop"). tanaike-lab enforces a Human-AI Synergy Model, where the human PI retains strategic direction while AI subagent matrices accelerate logical formulation, code execution, empirical auditing, and multi-axis peer reviews.
Positioning as a Cognitive Friction Eliminator: Traditional scientific workflows consume massive cognitive bandwidth on operational friction—debugging scripts, interpolating non-uniform temporal grids, adjusting graphics for color universal design, and fixing LaTeX compilation errors. tanaike-lab acts as a cognitive accelerator, eliminating operational friction so human researchers can focus on high-level strategic reasoning.
Triple-Domain Architecture: tanaike-lab operates across three interconnected domain pillars:
- Academic & Natural Sciences: Geophysical modeling, computational fluid dynamics (CFD), quantum chemistry, and material science.
- Generative AI & LLM Engineering: Prompt architecture, RAG vector retrieval pipelines, Multi-Agent orchestration, token budget compression, and LLM benchmarks.
- Google Ecosystem: Google Apps Script (GAS) libraries, Google Workspace automation (Drive, Sheets, Docs, Gmail, Forms), and Google Cloud/Workspace APIs with quota limit management.

8. Summary

The release of our updated manuscript Unification Theory of Lithosphere-Atmosphere-Ionosphere Coupling via Acoustic-Gravity Waves (LAIC-AGW)... on ESS Open Archive marks a major leap in earthquake science. By proving that pre-seismic enthalpy anomalies ($\delta \theta_e = 5.96\text{--}15.47\,\text{K}$) can be captured hours prior to shaking using crowdsourced IoT weather networks with 100% false alarm elimination ($P_{\text{eq}} \le 4.8\%$), this research shifts earthquake warning from reactive seconds to proactive hours.

It should be recognized that the analytical results, physical interpretations, and conclusions presented in this study represent one of many diverse scientific perspectives and theoretical approaches within the evolving domain of earthquake physics. Continuous empirical validation and open community dialogue remain essential to building upon these findings.

DEV Community: Tanaike

Beyond Passive AI Rewrites and Vibe Coding in Google Docs

Scaling a Multimodal AI Writing and Code Review Coach Across Classrooms and Research Labs with Gemini and Google Apps Script

1. The Deployment Challenge in Education, Research Labs & Organizations

2. How v1.0.3 Solves This with a Single Unified Script

A. Priority-Locked Dual API Key Resolution (ScriptProperties ➔ UserProperties)

B. Dual Menu Registration for Both Private Marketplace Add-ons and Container-Bound Scripts (onOpen & onInstall)

3. Why DocuMentor AI Is Transformative for Academia, Scientific Research, Higher Education & Engineering Training

1. Combating "Cognitive Debt" and "Cognitive Surrender" in Academic & Student Writing

2. True Cross-Modal Consistency Verification (Prose ⇄ Tables ⇄ Figures) for Research Papers

3. Distilling Co-Author, Advisor & Peer-Review History into Long-Term Learning (INCLUDE_RESOLVED_HISTORY)

4. Protecting Unpublished Research Data & Scaling Across Classrooms

5. Beyond Prose: Why DocuMentor AI Is Ideal for Multi-Language Script Learning, Code Review & Engineer Training

4. Live Demonstration (v1.0.3): Inside the Sidebar Dashboard, Prose Modes & Interactive Code Review

Inside the v1.0.3 Sidebar Dashboard (sidebar_v103.jpg)

Choosing the Right Model: Gemini 3.8 Flash vs. Gemini 4 Argon

Case A: Running "💡 Hint-Only Mode" (Active-Recall Coaching Without Spoiling the Answer)

Case B: Running "🚀 Suggest & Coach Mode" with Resolved Review History (Rejection-Aware Surgical Edits)

Case C: Beyond Prose — Interactive Multi-Language Code Review & Script Coaching (code_review_mode_result.jpg)

5. Comparison: Individual Mode vs. School, Organization & Academic Lab Mode

6. Quick Walkthrough of the Two Setup Workflows

Workflow A: Individual Setup (3 Minutes)

Workflow B: Zero-Code School, University & Organization Rollout (10 Minutes for IT Admins)

Summary

Building a Multimodal, Suggestion-Based AI Writing Coach with Gemini and Google Docs

Purpose, Motivation & Addressing the "AI-Induced Cognitive Offloading" Problem

Purpose of Development & Effectiveness Against AI-Induced "Thought Stopping"

Technical Inspiration

1. Non-Destructive, Transparent AI Editing (WriteMode.SUGGEST)

2. True Multimodal Manuscript Understanding (Text, Tables & Figures)

3. Flexible Scope Control (Entire Active Tab vs. Selection Only)

4. Pedagogical Writing Coach & Learning Summary Dialog (Learning from Both AI and Other Users' Reviews)

From Black-Box Rewriting to an Active Self-Learning Loop: Architecture & 4-Stage Workflow

Step-by-Step Installation & Usage Guide

1. Create or Open a Google Document

2. Copy and Paste the Script Files (src/)

3. Reload Google Docs & Launch from the Custom Menu

4. Configure Settings & Run Proofreading (How to Use the Sidebar)

Testing with the Sample Manuscript (sample/) & Live Demonstration

How to Load the sample/ Files into Google Docs

Before Proofreading: The sample/ Manuscript Loaded into Google Docs

After Running DocuMentor AI on the sample/ Manuscript

Holistic Self-Learning: The "Writing Coach & Learning Summary" Generated from the sample/ Manuscript

How This Summary Actively Promotes Self-Learning and Skill Growth

Expected Impact & Practical Use Cases

Expected Benefits

Ideal Scenarios

Continuous Evolution & Feature Updates: Performance Optimization and Pedagogical Enhancements

Streamlining Large-Manuscript & Selection-Scoped Proofreading via the Gemini File API

Active-Recall Hint-Only Coaching Mode & Resolved Review History Extraction

Version-by-Version Feature Comparison

How These Updates Enhance Practical Workflows

Summary

Reflections on the Power of Gemini 4 Argon

1. The Initial Prompt Used to Build the Application

2. One-Shot Feature Implementation That Ran Without a Single Error

3. Flawless Document Index Calculation (startIndex / endIndex) from documents.get

4. Autonomous Multi-Step Pipeline for Extracting Google Docs Figures (contentUri ➔ Binary ➔ Base64 / Gemini File API)

5. Additional Technical Highlights That Showcased Gemini 4 Argon's Depth

AlphaEvolve and Gemini: Autonomous Algorithm Discovery for Unified Disaster Prediction

1. The Invisible Whisper Before the Catastrophe — And a New Way to Do Science

Why Is Predicting Natural Disasters So Excitingly, Terrifyingly Difficult?

The Core Message of This Article: Autonomous Algorithm Creation for Model and Theory Building

2. The Secret Life of Weather Data: Why the Atmosphere Senses the Earth’s Fury

Walking Through Figure 1: Three Hazards Captured on Balconies

3. My Long Journey of Crafting Disaster Models by Hand

Understanding the Bottlenecks in Figure 2

Why Human Hand-Tuning Fails When Hazards Collide

4. Enter AlphaEvolve: An AI That Autonomously Writes Algorithms to Build Models and Theories

Why Autonomous Symbolic Algorithm Creation Beats Black-Box Neural Networks (Figure 3)

Walking Through Figure 4: How Gemini Evolves the Algorithm

5. How to Use AlphaEvolve: A Practical Guide to Autonomous Algorithm Creation

Step-by-Step Walkthrough of Figure 5

Step 1: Define the Seed Skeleton with # EVOLVE-BLOCK Markers (Figure 5, Column 1)

Step 2: Connect the Evaluator Harness & Gemini Closed Loop (Figure 5, Column 2)

Step 3: The 3-Level Autonomous Elevation — Algorithm to Model to Theory (Figure 5, Column 3)

6. How We Fed 175,363 Real Disaster Observations into AlphaEvolve

Walking Through Figure 6: The 5-Script Data-to-Discovery Pipeline

Stage 1: Raw Data Extraction & Hardware Authentication (01_fetch_multi_hazard_data.py — Figure 6, Column 1 Top)

Stage 2: Immutable Physics Core & Read-Only Tensor Pre-Caching (02_immutable_physics_core.py — Figure 6, Column 1 Middle & Bottom)

2. How `v1.0.3` Solves This with a Single Unified Script

A. Priority-Locked Dual API Key Resolution (`ScriptProperties` ➔ `UserProperties`)

B. Dual Menu Registration for Both Private Marketplace Add-ons and Container-Bound Scripts (`onOpen` & `onInstall`)

2. True Cross-Modal Consistency Verification (`Prose ⇄ Tables ⇄ Figures`) for Research Papers

3. Distilling Co-Author, Advisor & Peer-Review History into Long-Term Learning (`INCLUDE_RESOLVED_HISTORY`)

4. Live Demonstration (`v1.0.3`): Inside the Sidebar Dashboard, Prose Modes & Interactive Code Review

Inside the `v1.0.3` Sidebar Dashboard (`sidebar_v103.jpg`)

Choosing the Right Model: `Gemini 3.8 Flash` vs. `Gemini 4 Argon`

Case C: Beyond Prose — Interactive Multi-Language Code Review & Script Coaching (`code_review_mode_result.jpg`)

1. Non-Destructive, Transparent AI Editing (`WriteMode.SUGGEST`)

2. Copy and Paste the Script Files (`src/`)

Testing with the Sample Manuscript (`sample/`) & Live Demonstration

How to Load the `sample/` Files into Google Docs

Before Proofreading: The `sample/` Manuscript Loaded into Google Docs

After Running DocuMentor AI on the `sample/` Manuscript

Holistic Self-Learning: The "Writing Coach & Learning Summary" Generated from the `sample/` Manuscript

3. Flawless Document Index Calculation (`startIndex` / `endIndex`) from `documents.get`

4. Autonomous Multi-Step Pipeline for Extracting Google Docs Figures (`contentUri` ➔ Binary ➔ Base64 / Gemini File API)

Step 1: Define the Seed Skeleton with `# EVOLVE-BLOCK` Markers (Figure 5, Column 1)

Stage 1: Raw Data Extraction & Hardware Authentication (`01_fetch_multi_hazard_data.py` — Figure 6, Column 1 Top)

Stage 2: Immutable Physics Core & Read-Only Tensor Pre-Caching (`02_immutable_physics_core.py` — Figure 6, Column 1 Middle & Bottom)

Stage 3: The 3-Tier Defensive Evaluator Harness (`03_alpha_evolve_dispatcher_evaluator.py` — Figure 6, Column 2)

Stage 4 & Stage 5: Campaign Execution & Standalone Verification (`04` & `05` — Figure 6, Column 3)

3. The Algorithmic Core: Differential CDC & Atomic `MERGE INTO`

3.3 Atomic `MERGE INTO` SQL Synthesis

Step 4: Infrastructure Provisioning & `default_data` Staging