Stock Manager

Smart multi-agent restocking system for a steam bun shop

Google ADK Gemini 2.5 Flash AlloyDB Google Sheets MCP FastAPI Cloud Run

Project Overview & Problem Statement

Challenge: A steam bun shop restocks by over-ordering slow-moving items and running out of fast sellers. Without data-driven insights, the owner wastes money on excess stock and loses sales from stockouts.

Solution: Stock Manager uses multiple AI agents to automate restocking. It analyzes sales trends, monitors stock levels, predicts potential stockouts, and generates a purchase order in Google Sheets — all from a single question.

Key Benefits

Application Features

Sales Trend Analysis

Queries AlloyDB for average daily sales per product and compares week-over-week trends to identify fast movers, slow movers, and rising demand items.

Stock Level Monitoring

Checks current inventory against reorder points for all 18 products. Flags items as critical (below 50% of reorder point), low, or healthy.

Predictive Restocking

Combines sales trends with inventory data. Items with rising demand (10%+ increase) and stock within 1.5x of reorder point are flagged for early restocking.

Automated Purchase Order

Creates a purchase order grouped by supplier with product names, quantities, and contact details. Pushes directly to Google Sheets via MCP.

Live Inventory Panel

Left sidebar displays real-time stock levels for all products with color-coded status badges. Updates reflect the latest database state.

Chat Interface

Conversational UI with quick-action buttons for common queries. Supports markdown tables, bold text, and clickable links in responses.

AI Integration & Intelligence

Multi-Agent Orchestration (Google ADK)

Uses SequentialAgent to chain three specialized sub-agents: Sales Analyst, Inventory Checker, and Restock Decider. Each agent has its own tools and instructions.

Sales Analyst Agent

Queries AlloyDB with two SQL tools: daily sales summary and week-over-week trend comparison. Identifies top 5 fast/slow movers and all rising-demand products.

Inventory Checker Agent

Queries AlloyDB for current stock levels and low-stock items. Reports critical/low items with reorder quantities and supplier contact details.

Restock Decider Agent

Synthesizes findings from both previous agents. Applies restocking rules and generates a purchase order pushed to Google Sheets via MCP tool.

Technical Architecture & Implementation

Backend Stack

Python 3 FastAPI Google ADK Gemini 2.5 Flash SQLAlchemy pg8000

Data & Storage

AlloyDB (PostgreSQL) Google Sheets (MCP) gspread

Deployment & Infrastructure

Google Cloud Run Docker VPC Connector asia-southeast1

System Architecture

Development Setup & Installation Guide

Prerequisites

Quick Start Installation

# Clone the repository git clone https://github.com/lyven81/ai-project.git cd ai-project/projects/stock-manager # Install dependencies pip install -r requirements.txt # Set up the database python db_setup.py # Run the app python main.py

Environment Configuration

GOOGLE_CLOUD_PROJECT=your-project-id GOOGLE_CLOUD_LOCATION=asia-southeast1 GOOGLE_GENAI_USE_VERTEXAI=true DB_HOST=your-alloydb-ip DB_USER=postgres DB_PASS=your-password DB_NAME=stockmanager GOOGLE_SHEETS_ID=your-spreadsheet-id

Deployment on Google Cloud Run

gcloud run deploy stock-manager \ --source . \ --region asia-southeast1 \ --allow-unauthenticated \ --vpc-connector your-vpc-connector \ --set-env-vars "GOOGLE_CLOUD_PROJECT=...,DB_HOST=..." \ --memory 1Gi \ --timeout 300

Production Notes

Key Metrics

3
AI Agents in Pipeline
18
Products Tracked
9,852
Sales Transactions
4
Suppliers Managed

Business Value