Inspiration
ROACLAW was inspired by a simple frustration: advertising teams have more dashboards and AI suggestions than ever, yet they still lack a trustworthy operating layer between an insight and a money-changing action. We wanted to build the missing layer—a system that is useful before, during, and after an action because it can explain the proposal, enforce the boundary, verify the result, and preserve evidence.
What it does
An operator sets a goal and reviews campaign evidence in English or Arabic. In a separate proof API, Gemini 3.5 Flash converts the goal and an explicitly synthetic campaign snapshot into a closed recommendation contract. Deterministic policy checks action type, confidence, change limits, lead pacing, and the spend guardrail. The API changes only response-local synthetic state, checks the computed result, and returns a clearly scoped non-persistent ledger. The reviewed UI fixture separately demonstrates approval, mismatch, unknown-dispatch, reconciliation, and compensation states instead of hiding failure paths.
How we built it
We built the judged product journey with React, TypeScript, Vite, and a bilingual RTL-aware interface. A separate FastAPI proof service uses the official Google GenAI SDK with Vertex AI and Gemini 3.5 Flash. Pydantic validates the request; an exact-key parser validates the model JSON before deterministic Python policy runs. The API performs a response-local synthetic state transform and returns its computed check and ledger with explicit scope fields. The web build and API share one Docker image built by Google Cloud Build for Cloud Run, but the fixture UI does not invoke the proof endpoint. Separately, the repository contains a security-reviewed Google Ads REST v25 adapter behind a private executor boundary; live OAuth mutation is not represented as completed evidence.
Challenges we ran into
The hardest problem was preserving a strict boundary between reasoning and authority while still delivering an understandable demo. Provider timeouts and ambiguous dispatch also forced us to model “unknown” as a real state rather than retrying blindly. We had to make English and Arabic workflows equivalent, keep tenant resolution server-side, reject missing measurement instead of fabricating zeroes, and disclose exactly which provider effects are simulated.
Accomplishments that we're proud of
- A complete EN/AR Goal → Monitor → Proposal → Approval → Readback → Ledger journey.
- A Gemini SDK/API recommendation path with deterministic policy and fail-closed tests.
- Explicit mismatch, unknown-dispatch, reconciliation, and compensation behavior.
- A Cloud Run-ready container that serves both the product journey and proof API.
- Reproducible focused verification: 44 web tests, 18 browser scenarios, and 14 SDK/API/policy tests.
- A truthful separation between the implemented Google Ads adapter and unverified live Google Ads mutation.
What we learned
Agent quality is not just model quality. Reliable agentic operations require narrow contracts, deterministic authorization, capability discovery, idempotency, exact readback, and durable evidence. We also learned that RTL support must shape the workflow from the beginning, and that honest limitation labels make a technical demo stronger rather than weaker.
What's next for ROACLAW
Next we will complete a consented Google Ads test-account OAuth proof, add scheduled measurement ingestion, expand provider capability discovery, and move from synthetic execution to policy-gated sandbox mutations with rollback evidence. We also plan to add voice as untrusted input, richer anomaly investigation, and carefully reviewed operator workflows for more channels.
How We Used AI
Gemini 3.5 Flash analyzes a goal plus an explicitly synthetic campaign snapshot and returns one closed recommendation containing an action, bounded change percentage, confidence, and rationale. It cannot authorize, dispatch, access secrets, issue generic HTTP/SQL, or bypass policy. Malformed, unsupported, low-confidence, or excessive recommendations fail closed.
How We Used Codex
Codex helped turn the locked product brief into governed task packets, implementation, tests, architecture documentation, bilingual verification, and a reproducible submission package. Human-approved product and security constraints remained authoritative; generated work was reviewed through automated checks and explicit evidence labels.
Key Features
- Bilingual English and Arabic/RTL operator journey.
- Guided and Operator experience modes kept separate from autonomy levels.
- Typed Gemini recommendation contract.
- Deterministic policy and approval gates.
- Response-local synthetic state transform with an explicit computed-check scope.
- Stable action-ID binding without claiming idempotency reservation or persistence.
- Response-local proof receipt, plus a separate durable-ledger runtime boundary.
- Mismatch, unknown-dispatch, reconciliation, and compensation states.
- Private official Google Ads REST v25 adapter boundary.
- Visible
SIMULATED WORKSPACEdisclosure throughout judged provider effects.
Architecture
The React/Vite web application and FastAPI proof API are packaged into one Cloud Run container as separate judge surfaces. The fixture UI does not call the proof endpoint. The API calls Gemini 3.5 Flash through the Google GenAI SDK on Vertex AI, validates the request with Pydantic, manually validates the closed model result, and passes it into deterministic policy. It changes only response-local synthetic state, checks the computed result, and returns a non-persistent ledger. The production provider adapter is isolated behind a private executor boundary and is not invoked by the hackathon demo.
Architecture file: docs/release/assets/roaclaw-architecture.png
Built With
- cloud-run
- docker
- fastapi
- firebase-admin-sdk
- gemini-3.5-flash
- google-ads-api
- google-cloud-build
- google-genai-sdk
- higgsfield
- playwright
- postgresql
- pydantic
- pytest
- python
- react
- seed-audio-1.0
- typescript
- vertex-ai
- vite
- vitest
