AppealOS

• 

• 

Inspiration

Platforms already use algorithms to judge people. A delivery rider, independent seller, creator, or developer can lose access to their account, income, or funds because of an automated risk decision, yet their only recourse is often a blank appeal form with no context.

That power imbalance inspired AppealOS.

We wanted to build a digital advocate for people affected by algorithmic decisions: an agent that does more than explain what happened. It should reconstruct the facts, identify the relevant policy, prepare a grounded appeal, take authorized action, respond to follow-up requests, and continue until the user receives a clear outcome.

Our guiding idea was:

Platforms have tireless algorithms. People deserve a tireless agent that can demand due process.

What it does

AppealOS turns an account suspension into an executable, evidence-backed appeal case.

Our demo uses a fictional delivery platform called MockDrop. A rider is suspended for “abnormal location activity” after a normal cellular handoff is mistakenly classified as location fraud.

AppealOS:

1. Reads and extracts the suspension notice.
2. Identifies the allegation, account, and appeal deadline.
3. Asks the user to select exactly which evidence Gemini may analyze.
4. Builds a citation-backed account of what happened.
5. Matches the evidence against the platform’s published policy.
6. Produces structured appeal claims.
7. Presents a bounded AppealMandate for explicit approval.
8. Submits the appeal to MockDrop.
9. Receives a request for supplemental device evidence.
10. Discloses only the authorized device log.
11. Tracks the platform’s decision.
12. Independently verifies that the account is active before declaring success.

The result is a complete transition from:

SUSPENDED → SUPPLEMENT_REQUESTED → APPROVED → ACTIVE

The user approves the scope once. The agent then completes the authorized multi-step workflow without requiring the user to operate every intermediate button.

Gemini can interpret and draft, but it cannot grant itself authority.

How we built it

AppealOS uses a two-service architecture:

• AppealOS Runtime: Python, FastAPI, Google ADK, and Gemini 3.5 Flash.
• MockDrop: A Node.js platform simulator with account, appeal, supplement, receipt, and idempotency APIs.

Google ADK runs typed LlmAgent tasks for:

• notice extraction;
• evidence-relevance analysis;
• grounded claim drafting.

We use Pydantic schemas to validate structured Gemini output. Deterministic Python code then verifies artifact IDs, policy clause IDs, confidence values, consent scope, mandate constraints, destinations, and supplement limits before anything can affect external state.

Firestore provides durable case recovery when running in Google Cloud. Each case is loaded by case_id, so a workflow can survive a service restart or continue after a partial failure.

Pub/Sub provides the event-driven path for platform callbacks such as:

• SUPPLEMENT_REQUESTED;
• DECISION_APPROVED;
• DECISION_REJECTED.

The consumer validates the Pub/Sub envelope, optionally verifies Google OIDC tokens, binds each event to the expected case, account, and appeal, and deduplicates external event IDs.

Every case transition is added to a hash-chained timeline. Changing an earlier event invalidates the chain, making the audit trail tamper-evident.

The user interface is a focused case workspace that displays:

• current case state;
• selected evidence and hashes;
• the approved mandate;
• agent actions;
• platform receipts;
• the complete event timeline;
• the final verified account status.

Both services are packaged for Google Cloud Run, with Firestore for state and Cloud Logging-compatible structured logs for observability.

Challenges we ran into

The hardest challenge was balancing autonomy with user control.

A fully autonomous agent that silently reads every file and submits content would recreate the same power problem AppealOS is meant to challenge. We separated analysis consent from action authorization and made both explicit, scoped, expiring objects.

Another challenge was treating Gemini as an untrusted reasoning component. Structured output alone is not enough. The model could still cite an unauthorized artifact or invent a policy reference. We added deterministic validation after every model call and kept all external writes outside the model.

Retries and duplicate events were also difficult. Platform callbacks may be delivered more than once, and a user may retry after a partial failure. We added stable idempotency keys, external-event deduplication, resumable states, and serialized mutation handling so the same mandate can safely continue without repeating the real-world action.

Finally, we had to make a complex workflow understandable in a short demo. We reduced the scope to one allegation, three evidence artifacts, one policy profile, one supplement cycle, and one clear recovery outcome.

Accomplishments that we're proud of

We are proud that AppealOS is not a chatbot or a text-generation wrapper. It performs a real, inspectable workflow across a platform boundary.

Specific accomplishments include:

• explicit evidence consent before Gemini processing;
• a bounded mandate that cannot silently expand its authority;
• autonomous submission, supplementation, tracking, and verification;
• durable case recovery by identifier;
• idempotent external actions;
• strict Pub/Sub event binding and deduplication;
• a tamper-evident event timeline;
• independent account-status verification before claiming success;
• truthful runtime evidence exposing the Gemini model, ADK version, storage backend, and Cloud Run revision;
• 31 Python tests and seven Node.js HTTP integration tests covering authorization, recovery, concurrency, idempotency, malformed events, and timeline tampering.

Most importantly, the product’s architecture reflects its values: the agent works for the person being governed by the algorithm.

What we learned

We learned that trustworthy agents need more than good prompts. They need explicit capabilities, narrow authority, deterministic checks, durable state, receipts, and safe retry behavior.

We also learned that the best division of responsibility is:

• Gemini handles ambiguous language and reasoning.
• Deterministic code handles authorization and state transitions.
• External systems provide receipts.
• The user defines the boundaries.

An agent becomes useful when it can act. It becomes trustworthy when every action can answer:

• Who authorized this?
• Which evidence was permitted?
• Which destination was approved?
• What changed externally?
• How can the result be verified?

What's next for AppealOS

The next step is to turn the single-platform demo into an open appeal protocol.

We plan to add:

• adapters for creator, marketplace, gig-work, developer, and financial platforms;
• encrypted, user-controlled evidence storage;
• passkey-based authentication and mandate signing;
• policy versioning and automatic policy-change detection;
• human legal-aid and worker-organization escalation;
• privacy-preserving evidence disclosure;
• downloadable escalation packets for regulators or arbitration;
• stronger multi-instance workflow coordination;
• a public adapter SDK for building new appeal integrations.

The long-term goal is not to guarantee that every appeal succeeds. It is to guarantee that people can assemble their evidence, exercise their rights, demand a reasoned response, and keep acting until the process reaches an explicit outcome.

Built With

• cloud
• firestore
• logging
• pub/sub
• vertex