Bureaucracy OS

Life, without the paperwork maze.

Comment

Inspiration

Imagine saying “I need to move countries,” “I need to buy a home,” or “I need to get my mother a passport”—and watching the paperwork maze turn into a living, evidence-backed plan that actually gets the work done.

Today, the same goal usually means:

  • opening dozens of tabs and finding contradictory instructions;
  • asking friends which rules really apply;
  • tracking forms, documents, payments, appointments, travel, and office visits by hand;
  • discovering dependencies only after a deadline is missed; and
  • starting over when a law, schedule, price, or official requirement changes.

Search can tell someone what might apply. A chatbot can explain a form. Neither one coordinates the full journey to completion.

We wanted to build for the AI era: a personal operations layer that understands the outcome, constructs the applicable dependency graph, gathers evidence, watches for change, and completes every safe step the person has already authorized. The user remains the principal. Agents are capable operators—never invisible or unaccountable decision makers.

Bureaucracy OS exists to give ordinary people leverage over unavoidable complexity: agents do everything safely delegable, and humans do only what must remain human.

What it does

The product opens as a catalogue of real-life journeys: international relocation, home buying, passports, driving licences, child identity documents, and visas. Each uses the same platform primitives—journey graphs, an evidence vault, coordination, proactive monitors, a user constitution, bounded actions, human checkpoints, and an inspectable audit trail. Preview journeys are honestly labeled. The international-move journey is implemented end to end for this hackathon.

The live demo follows Priya Sharma, a transparent synthetic graduate student moving from Bengaluru to San Francisco. Bureaucracy OS has already prepared a stable plan of 12 obligations linked by 10 causal dependencies to six evidence sources. Her constitution permits free, reversible coordination with a known university office, limits autonomous spending to $100, requires evidence for consequential claims, and reserves consequential submissions for Priya.

Then an official university message moves mandatory orientation from August 25 to August 23—before her booked arrival. The system:

  1. receives the external change and starts an inspectable agent run;
  2. asks Gemini 3.7 Flash, through Google ADK, for a typed impact assessment;
  3. validates every proposed node and source against the known dependency graph;
  4. identifies five affected plans and three conflicts;
  5. sends a reversible, zero-cost inquiry to the allowlisted university recipient;
  6. refuses to change a $185 flight because it exceeds Priya's $100 authority limit;
  7. consumes an external reply offering a free remote-orientation path;
  8. preserves the original travel plan and holds the free slot;
  9. stops for Priya to personally accept the consequential acknowledgement; and
  10. records her decision and clears the final conflict.

Replaying the original event proves semantic idempotency: it is recorded and ignored, with no second email and no repeated graph mutation.

How we built it

The product is a FastAPI and JavaScript application deployed on Google Cloud Run. External changes can enter through a Google Pub/Sub push subscription. Google ADK 2.x runs an LlmAgent backed by Gemini 3.7 Flash on Vertex AI's global endpoint. The model returns a typed Pydantic ImpactAssessment; application code intersects the proposed nodes with the known graph and validates the evidence before state may change.

A deterministic policy engine owns authorization. It evaluates cost, reversibility, submission risk, evidence presence, and recipient allowlists. Gemini can interpret and propose, but it cannot grant itself permission. Firestore stores the graph, sources, actions, traces, approval, and processed event IDs. The Gmail adapter supports explicit OAuth consent, signed OAuth state, narrow scopes, an allowlisted logical recipient, and durable refresh-token storage in Secret Manager. When Gmail is not connected, the public demo clearly uses a controlled outbox so the full state machine remains safe and reproducible.

The core architectural principle is: Gemini interprets; deterministic code authorizes. Language-model judgment is useful for understanding a changed real-world message. It is not acceptable as an invisible permission system for money, legal declarations, irreversible actions, unknown graph mutation, or retries.

System architecture

Bureaucracy OS system architecture

The execution path is deliberately split between probabilistic interpretation and deterministic authority:

  1. Perceive: Gmail or Pub/Sub delivers a changed real-world signal to Cloud Run.
  2. Interpret: Google ADK invokes Gemini 3.7 Flash on Vertex AI and requests a typed ImpactAssessment.
  3. Verify: Application code validates every proposed node, dependency, and evidence source against the known journey graph.
  4. Authorize: The deterministic policy engine evaluates cost, reversibility, submission risk, evidence, and recipient allowlists.
  5. Act: Only already-authorized, bounded actions are executed; consequential or over-limit actions become human decisions.
  6. Observe: External replies and newly gathered evidence re-enter the graph.
  7. Remember: Firestore stores events, graph mutations, traces, policy results, actions, approvals, and idempotency keys.

Gemini interprets; deterministic code authorizes. The model can propose what a change means, but it cannot grant itself permission to spend money, submit declarations, contact unknown recipients, mutate unknown graph nodes, or repeat an external effect.

Technologies

  • Gemini 3.7 Flash on Vertex AI
  • Google Agent Development Kit 2.x
  • Google Cloud Run
  • Google Firestore
  • Google Pub/Sub
  • Google Secret Manager
  • Gmail API and Google OAuth
  • Google Cloud Build and Artifact Registry
  • FastAPI, Pydantic, Python, JavaScript, CSS, and SVG

Other data sources

The public scenario uses transparent synthetic records:

  • a fictional admission letter;
  • an international-student onboarding excerpt;
  • a flight itinerary;
  • a housing move-in confirmation;
  • an orientation invitation and changed-orientation notice; and
  • a university reply offering a remote path.

No real student, university, immigration, or travel data is included. The optional Gmail proof sends only between accounts controlled by the operator.

Challenges

  1. Separating interpretation from authority. A model can plausibly explain why a flight should change; that does not mean it may spend money. We narrowed model output to a typed assessment, verified every proposed graph node, kept authorization in deterministic code, and exposed both reasoning and policy results in the interface.

  2. Communicating a platform rather than a bespoke student tool. We rebuilt the experience around a generic journey catalogue and reusable platform primitives. The student move is one deep, working proof; home buying, passports, licences, identity documents, and visas demonstrate the extensible product direction and are honestly labeled as previews.

  3. Making background agents safe to retry. Pub/Sub is at-least-once, so idempotency is a product requirement. We persist delivery IDs and add a semantic guard for the same real-world change. Judges can replay the event inside the product and see that no second email or duplicate graph mutation occurs.

Accomplishments

  • A coherent platform for many bureaucratic outcomes, not a one-scenario dashboard.
  • A complete non-chat workflow that perceives, reasons, verifies, acts, observes, escalates, and remembers.
  • Live Gemini 3.7 Flash inference through Google ADK, visible in the agent trace.
  • Pub/Sub → Cloud Run → ADK → Vertex AI → Firestore infrastructure.
  • A constitution and deterministic policy boundary judges can inspect and test.
  • Meaningful human control: every safe step is finished before the user is asked for the one irreducible decision.
  • Evidence provenance on every consequential claim and action.
  • Semantic idempotency demonstrated through the product itself.
  • A responsive, accessible web experience with an outcome catalogue, journey setup, dependency graph, evidence vault, decisions, activity, and constitution.
  • Nineteen automated tests covering graph integrity, policy, model-output validation, Pub/Sub decoding, OAuth-state security, the complete scenario, approval, and retry behavior.

What we learned

  • Reliability comes from the system around the model. Structured output narrows the interface, graph validation constrains interpretation, and deterministic policy owns authority.
  • Human-in-the-loop should not mean “ask before everything.” Good agents finish reversible work already authorized and ask only for a decision the human should genuinely own.
  • Provenance is a product feature. Consequential claims and actions should always point back to the source and policy that justified them.
  • Retry safety is part of user trust. External IDs and semantic idempotency make proactive background execution safe.
  • The best agent action is often the least dramatic one. Asking the right official question can preserve options and avoid an unnecessary $185 flight change.

What's next

  • authenticated, tenant-isolated workspaces;
  • document upload, extraction, classification, and expiry tracking;
  • calendar, travel, transport, payment, and appointment connectors;
  • durable Gmail watches and official-source monitors;
  • encrypted per-user credentials and policy simulation before enabling a new action class; and
  • journey modules for home buying, licences, identity, eldercare, benefits, and employee onboarding.

The goal is not to replace lawyers, accountants, public officials, or other qualified experts. It is to coordinate the unavoidable process, explain it in plain language, preserve the person's options, and return control to the person who must live with the outcome.

Built With

  • fastapi
  • firestore
  • gemini-3.7-flash
  • gmail-api
  • google-adk
  • google-cloud-run
  • javascript
  • pub-sub
  • pydantic
  • python
Share this project:

Updates

Submission history