The Cabinet Agentic Suite

Inspiration

The Crafters Hub is a woodworking and woodturning school in El Shorouk City, Cairo, Egypt — co-founded by Hosam Elshanawany and Mostafa Fahmy. Mostafa is the woodworking master, the cornerstone of the workshop, the person who made the craft culture real. He is currently in a severe coma and unable to teach. The workshop's physical operations are paused.

The knowledge built together over years — in lessons, in conversations, in hours of answering students' WhatsApp questions — lives in The Cabinet's knowledge base: 553 entries, live in PostgreSQL. This project keeps that knowledge alive, growing, and reachable for the students who still need it.

What it does

The Cabinet Agentic Suite is a three-agent system built with Google ADK 2.7.1: The entire system is controlled through a custom-built, React-based Control Panel UI, bringing enterprise-grade agent orchestration to a sleek, user-friendly workshop dashboard.

Agent 1 — Lesson Ingest Agent (Hybrid Cloud): Fetches a YouTube transcript and sends it to our Google Cloud Run microservice. The Cloud Run service uses Gemini 3.6 Flash with a structured output schema to extract the knowledge (technique, tools, safety, steps), and stores the JSON payload directly into a Google Cloud Storage (GCS) bucket. The local agent then reads the GCS bucket, generates a 3072-dim vector with gemini-embedding-2, and stores it in the on-premise PostgreSQL database.

Agent 2 — Research & Answer Agent: Answers woodworking questions from teachers and students. It searches the ingested knowledge base first (pgvector cosine similarity), falls back to pre-approved trusted websites (AAW, Popular Woodworking), then synthesizes using Gemini. Every answer is stored back in the database as a Q&A pair — this is the Knowledge Flywheel. The second time a similar question arrives, it is answered from local storage in milliseconds at zero API cost.

Agent 3 — Finance Sentinel: Scans the school's production finance database (READ ONLY) for unmatched income transactions and matches them to student enrollment records by amount delta. When confidence exceeds 60%, it sends a WhatsApp message to Hosam via Meta's Cloud API: "Reply APPROVE-{id} or REJECT-{id}." It never auto-modifies a single financial record. Human approval is required for every write.

How we built it

• Google Cloud Run — Serverless hosting for the AI extraction backend (FastAPI)
• Google Cloud Storage — Bridge storage between the cloud extraction service and the on-premise database
• Google ADK 2.7.1 — Agent class + @tool decorator + Runner.run_async() for orchestration
• Gemini 3.6 Flash — structured knowledge extraction (JSON schema output) + answer synthesis
• gemini-embedding-2 — 3072-dim vectors for semantic similarity search
• PostgreSQL + pgvector — on-premise vector store, zero hosting cost
• YouTube Transcript API 1.2.4 — transcript fetching without a browser or scraping
• Faster-Whisper — local video transcription at $0 (runs on school's Quadro P1000 GPU)
• Meta WhatsApp Cloud API v20.0 — human-in-the-loop approval channel for Finance Sentinel
• React / Vite / TailwindCSS — Frontend Control Panel UI FastAPI / Python 3.13 / psycopg2 — Unified API Backend

The system uses a true Hybrid Cloud architecture: heavy AI workloads run on Google Cloud Run and GCS, while the vector database stays on the school's own on-premise server.

Challenges we ran into

• pgvector index dimension cap: Both ivfflat and hnsw index types cap at 2000 dimensions in our pgvector version. gemini-embedding-2 outputs 3072 dimensions. Solution: drop the index and use sequential cosine scan (fast enough at <10K rows for the demo window; index can be added post-competition after a pgvector upgrade).
• youtube-transcript-api vs GCP: We initially tried to fetch YouTube transcripts directly in Cloud Run, but YouTube blocks requests from GCP IP ranges. We re-architected the system to fetch the transcript locally via the Agent, and POST the text directly to the Cloud Run extraction endpoint.
• **Windows console limitations: Python's rich library on a Windows console struggled with emoji encoding and formatting for complex markdown outputs. Solution: We abandoned the CLI entirely and built a unified FastAPI backend serving a gorgeous React web dashboard, proving that agentic tools need proper web UIs to be truly accessible to non-technical workshop staff.

Accomplishments that we're proud of

• Bypassed YouTube's GCP block by implementing a hybrid ingest pipeline (Local Fetch → Cloud Run Extract → GCS Save → Local DB Write).
• First YouTube video ingested end-to-end in 90 seconds.
• First research query after ingestion returned kb_match confidence — answered from OUR database, not Gemini general knowledge, on the very first try.
• Finance Sentinel is scanning the school's real production finance table in read-only mode — no mock data.
• Migrating our fragmented python scripts into a unified FastAPI gateway and a polished React Control Panel in under 24 hours.

What we learned

• ADK 2.7.1's @tool decorator with typed Python functions produces clean, Gemini-compatible JSON schema with minimal boilerplate.
• gemini-embedding-2 is significantly more capable than text-embedding-004 but emits 3072-dim vectors — any system assuming 768 dimensions will silently corrupt its vector store.
• The human-in-the-loop pattern via WhatsApp is more practical for a small school than any dashboard approval UI.

What's next

• Ingest the full Stuart Batty YouTube back-catalogue (~200 videos) to build a comprehensive woodturning knowledge base.
• Add a WhatsApp-facing research endpoint so students can ask questions directly in WhatsApp and get sourced answers.
• Add the Finance Sentinel approval handler (the write side of the loop — currently only the read + alert side is built).

Built With

• adk
• faster-whisper
• gemini-3.6-flash
• gemini-embedding-2
• google-adk
• google-cloud
• google-cloud-run
• google-genai
• meta-whatsapp-cloud-api
• pgvector
• postgresql
• psycopg2
• python
• rich
• youtube-transcript-api