StormShift

When a typhoon alert lands, a small shop's entire day rearranges itself—safely, durably, and with proof.

Comment

StormShift — Devpost submission

Status: release-ready; only the public video and Devpost project URL remain to be attached.

Title

StormShift

Tagline

When a typhoon alert lands, a small shop's entire day rearranges itself—safely, durably, and with proof.

Category

Taskmaster

Elevator pitch

StormShift is a resilient operations agent for independent shops facing severe weather. It receives a trusted warning event, locks the shop's current operating state, asks Gemini for a structured intent, compiles that intent into a deterministic plan, and carries authorized work through orders, hours, customer communications, inventory, and public status. Every external mutation has an idempotency key, verification receipt, ledger entry, and—where safe—a compensating action.

This is not another checklist generator. It is the execution and recovery layer a small team normally has to become by hand.

Inspiration

When a typhoon warning changes, a shop owner becomes a human integration layer. They inspect affected orders, change hours, contact staff and customers, protect inventory, and later reverse those changes while physically preparing the shop. One missed message or duplicate action creates more work at the worst possible moment.

The hard part is not producing advice. It is coordinating related side effects under partial failure without inventing facts or expanding authority.

What it does

  1. Accepts a signed, normalized weather event or clearly labeled historical replay.
  2. Rejects stale, irrelevant, out-of-region, conflicting, or downgrade events before model or tool use.
  3. Locks an immutable shop snapshot and uses Google ADK with Gemini 3.7 Flash to produce structured intent.
  4. Compiles that intent into six typed candidate actions and authorizes each with deterministic policy.
  5. Executes five bounded sandbox mutations across orders, calendar, notifications, inventory, and status assets.
  6. Refuses the proposed refund because financial authority is explicitly prohibited.
  7. Verifies ambiguous remote outcomes before retrying and resumes from durable checkpoints after a transient failure.
  8. Shows plan, policy, receipts, before/after state, model assurance, compensation links, and a hash-chained ledger in one live operations surface.

How we built it

The backend is Python 3.12 and FastAPI. Google ADK on Vertex AI runs Gemini 3.7 Flash as the intent planner. A deterministic compiler converts the provider-compatible wire result into strict per-action Pydantic models; deterministic policy remains the authorization boundary.

Four narrow assurance roles are visible and independently receipted:

  • gemini-embedding-001 retrieves the applicable policy clauses on Vertex AI.
  • gemini-2.5-pro critiques the plan independently on Vertex AI.
  • gemma-4-26b-a4b-it challenges bilingual and prohibited-capability risk through the Gemini Developer API; it cannot authorize anything.
  • text-multilingual-embedding-002 checks Chinese/English alignment on Vertex AI.

The workflow is a persisted saga with typed actions, retry/verification rules, compensation, globally unique idempotency keys, and a SHA-256 ledger chain. A local SQLite materialized view is mirrored through immutable Firestore generations with a compare-and-swap manifest. Cloud Run is intentionally constrained to one writer instance and one concurrent mutation request.

The React/TypeScript interface is a purpose-built operations console rather than a chat transcript. It makes failure, denial, recovery, and evidence first-class states.

Reliability and safety

Gemini proposes; code authorizes. The model cannot call unrestricted APIs, change policy, grant itself tools, or convert a financial denial into an approval. Every outbound factual claim is resolved against the signed event, locked snapshot, and policy clauses. Same event ID with different content is a conflict, not an idempotent replay. Ledger corruption quarantines the workflow instead of reporting success.

The golden path deliberately injects a transient inventory failure. StormShift reaches durable RETRY_WAIT, then resumes without duplicating an effect. A valid typhoon downgrade does not accidentally run closure work. Compensation uses compare-and-swap ownership so an older saga cannot undo a newer hold.

Live release results

  • Promoted release: champion-20260819-v11
  • Cloud Run revision: stormshift-00001-jar
  • Cloud Build: 9041d429-2467-4de1-bfc9-c8081cc1cec2
  • 50 backend tests passed; statement coverage: 85%
  • Ruff, Vitest, TypeScript, Vite, desktop/mobile Chromium E2E, Terraform, candidate, and public runtime gates passed
  • Live ADK planner: google-adk-structured-intent+deterministic-compiler on gemini-3.7-flash
  • Live model receipts: Vertex 3,072-dimensional policy embedding; Vertex independent critique; Gemini API Gemma challenge; Vertex 768-dimensional multilingual alignment
  • Golden result: five verified mutations, one deterministic refund denial, one durable retry, zero duplicate effects, and a valid 32-entry ledger chain
  • Exact live assurance gate passed three consecutive times before release

Google Cloud architecture

  • Google Agent Development Kit
  • Gemini 3.7 Flash, Gemini 2.5 Pro, Gemini Embedding, Text Multilingual Embedding, and Gemma 4
  • Vertex AI and Gemini Developer API
  • Google Cloud Run with a dedicated runtime service account
  • Named Firestore database stormshift
  • Cloud Build, Artifact Registry, IAM, Logging, and release-gated infrastructure

Data and honest limitations

The weather payload is an authentic, visibly labeled historical-replay fixture. Shop orders, recipients, policy, and inventory are purpose-built synthetic records. The adapters mutate persistent isolated sandboxes, not real commerce, calendar, messaging, payment, or emergency-warning systems. No customer is contacted and no purchase or refund is made. StormShift is an operating-work coordinator, not a weather forecaster or life-safety decision maker.

What we learned

The most useful agentic feature was not a longer plan; it was a smaller uncertainty window around every action. Provider-constrained output was still insufficient on its own, so the final design uses a flat ADK intent schema followed by a deterministic typed compiler. Model critics add real value when their context and action scope are complete, but they stay advisory. Durable retries became trustworthy only after verification receipts, ledger-integrity checks, payload-hash conflicts, and kill-point recovery were tested together.

Links

Testing instructions

Open the hosted application. Mutating demo controls prompt for the private judge admission code supplied in Devpost's private testing-instructions field. Choose Inventory · transient before, press Run signed replay, inspect RETRY WAIT, then press Resume checkpoint. Confirm five verified mutations, one refund denial, four live model receipts, and CHAIN VALID. The public repository also supports ./scripts/verify.sh and documents the exact local/cloud configuration without committing any secret.

Build disclosure

StormShift was newly built during the All Things Agentic Hackathon submission period. Libraries, Google services, AI coding assistance, the historical replay, synthetic fixtures, generated concept art, and all limitations are disclosed in the repository.

Built With

  • fastapi
  • firestore
  • gemini-2.5-pro
  • gemini-3.7-flash
  • gemma-4
  • google-agent-development-kit
  • google-cloud-run
  • react
  • typescript
  • vertex-ai
Share this project:

Updates