TidyBatch Agent — Devpost Submission

• 

  TidyBatch Agent

Problem Statement

Teams and individuals accumulate files with names like IMG_2034.jpg, FINAL_v3_REALLY_FINAL.pdf, and untitled_document_1.docx. Renaming them manually is tedious, inconsistent, and error-prone — especially across large batches from multiple contributors.

Solution

TidyBatch Agent is a lightweight autonomous multi-step agent that:

1. Accepts a project context and a batch of files from the browser.
2. Uses Gemini 3.5 Flash (Vertex AI) to read filenames and text snippets and propose meaningful, standardised replacements.
3. Runs a deterministic Python validator to enforce safety rules before any file is touched.
4. Copies files with their new names, packages them into a ZIP, and generates a full audit trail (JSON + CSV).
5. Lets the user download everything in one click.

Built to be deployed on Google Cloud Run as a stateless, serverless container.

How It Works

Browser → POST /triage
  → FastAPI reads files, extracts metadata
  → Agent calls Gemini via Vertex AI (google-genai SDK)
  → Gemini returns [{original, proposed, reason}] JSON plan
  → Validator enforces: extension preserved, no traversal, no reserved names, unique
  → Processor copies files, builds ZIP + audit
  → Browser gets session download links

Technologies

• Python 3.11 — core runtime
• FastAPI — async HTTP API
• Google GenAI SDK (google-genai 2.20.0+) — Gemini client
• Vertex AI (Gemini Enterprise Agent Platform) — publishers/google/models/gemini-3.5-flash at global endpoint
• Google Cloud Run — serverless container deployment
• Docker — container packaging
• stdlib only — zipfile, csv, tempfile, uuid (no heavy dependencies)

Google Cloud / Gemini Proof Points

• Gemini 3.5 Flash (publishers/google/models/gemini-3.5-flash) on Vertex AI Enterprise Agent Platform makes every filename-planning decision.
• The JSON rename plan is produced exclusively by Gemini 3.5 Flash — no hardcoded filename rules.
• Location: global endpoint (required for Gemini 3.x models); GOOGLE_GENAI_USE_ENTERPRISE=True set in runtime environment.
• Local development auth: Workload Identity Federation — the EC2 instance's AWS identity is federated to GCP via a WIF pool, allowing keyless access to Vertex AI with no long-lived credential files in the repository.
• Cloud Run deployment auth (planned): the Cloud Run service will use its attached runtime service account with roles/aiplatform.user — no keys, no WIF config, no credential files required at runtime.
• Cloud Build will be used to build and push the Docker image.

Challenges

• Parsing Gemini's JSON output reliably (markdown fences, trailing text). Solved with a defensive strip + json.loads + schema validation.
• Extension preservation: Gemini sometimes strips or changes extensions. Solved deterministically in the validator — the original extension always wins.
• Uniqueness without a database: implemented a seen-set dedup loop with sequential suffixes (-001, -002) in pure Python.
• Ephemeral file safety: temp dirs are cleaned immediately after ZIP is built, even if the copy step raises an exception.

Accomplishments

• True agentic pipeline: Gemini makes the naming decision, Python enforces safety.
• Zero-dependency validator: all safety checks are deterministic, auditable Python.
• Complete audit trail: every decision logged to JSON + CSV.
• Full test suite covering 14 validator edge cases and 9 processor scenarios.
• Cloud Run deployment with no database, no auth service, no message queue.

Lessons Learned

• Defensive JSON parsing from LLM output is essential — always strip fences, always validate schema, always fall back gracefully.
• Separating the AI decision layer from the deterministic enforcement layer makes agents more auditable and safer.
• Minimal stacks (no ORM, no queue, no vector DB) deploy faster and fail less.

Built With

• docker
• fastapi
• google
• python
• vertexai